Java 注释与文档注释

注释是写给「人」看的说明文字，编译器会直接忽略。给类、方法、关键逻辑写好注释，几个月后的自己或同事都能快速读懂代码。

单行注释 //

// 用来注释本行之后的内容：

public class LineComment {
    public static void main(String[] args) {
        int age = 18;              // 行尾注释：age 表示年龄
        // System.out.println(age);  整行被注释，不会执行
    }
}

多行注释 /* */

/* ... */ 可以跨多行包裹一段说明文字：

public class BlockComment {
    public static void main(String[] args) {
        /*
          这是一段多行注释，
          适合写比较长的说明。
        */
        System.out.println("注释被忽略，这行照常执行");
    }
}
// 输出：注释被忽略，这行照常执行

文档注释 /** */

以 /** 开头、*/ 结尾的注释叫文档注释，常写在类与方法前面，可用 javadoc 工具生成 HTML 格式的 API 文档。

javadoc 常用标签

标签	作用
@author	作者
@version	版本号
@since	起始版本
@param	描述方法的一个参数
@return	描述方法的返回值
@throws	描述可能抛出的异常

文档注释示例

给方法编写文档注释，用 @param 说明参数、@return 说明返回值：

public class Calc {
    /**
     * 计算两个整数的和。
     *
     * @author 张三
     * @version 1.0
     * @param a 第一个加数
     * @param b 第二个加数
     * @return a 与 b 相加的和
     */
    public static int add(int a, int b) {
        return a + b;
    }

    public static void main(String[] args) {
        System.out.println(add(2, 3)); // 输出：5
    }
}

在命令行执行 javadoc -d doc Calc.java，即可生成包含上述标签的网页文档，格式与官方 Java API 文档一致。

注释规范与作用

• 类头注明作者与用途；方法说明「做什么、参数和返回值是什么」。
• 注释重点写「为什么这么做」，不要复述代码本身。
• 调试时可临时注释语句，用后及时删除，不遗留大段无用代码。
• 注释不参与编译：javac 编译时直接丢弃，class 字节码中没有注释，反编译也看不到。

单行与多行注释记录思路，文档注释配合 @param、@return 等标签生成 API 文档，规范的注释让代码更易读、更易维护。