注释（单行、多行、文档注释）

注释是写给谁看的

代码是写给机器执行的，更是写给人看的。一个月后回头看自己写的代码，你大概率一头雾水。

注释就是你在代码里留给「未来的自己」和队友的便签。它解释这段代码在干什么、为什么这么写。

关键一点：注释会被编译器直接丢掉。它从不会进入 .class 文件，也就绝不会影响程序运行速度。你可以放心地写，不用担心拖慢程序。

单行注释

两个斜杠 // 开头，这一行后面的内容全是注释。

public class CommentDemo {
    public static void main(String[] args) {
        int age = 18;          // 用户年龄
        System.out.println(age);  // 打印年龄
    }
}

// 后面可以接在代码尾巴上，也可以独占一行。最适合写一句短说明。

多行注释

用 /* 开头、*/ 结尾，中间可以跨好几行。

public class BlockComment {
    public static void main(String[] args) {
        /*
         * 下面这段代码计算两个数字的和
         * 结果存到 sum 里
         */
        int a = 3;
        int b = 4;
        int sum = a + b;
        System.out.println(sum);
    }
}

文档注释

文档注释以 /** 开头、*/ 结尾。它长得很像多行注释，但地位特殊——专门用来生成 API 文档。

/**
 * 计算器工具类，提供基础的加法。
 * @author 码上学
 * @since 25
 */
public class Calculator {

    /**
     * 求两个整数的和。
     * @param x 第一个加数
     * @param y 第二个加数
     * @return 两数相加的结果
     */
    public static int add(int x, int y) {
        return x + y;
    }
}

开头的 /** 之后，通常先写一段总体说明，再跟上若干个 @ 开头的标签：

标签	作用	例子
@param	说明方法参数	@param x 第一个加数
@return	说明返回值	@return 相加的结果
@throws	说明可能抛的异常	@throws IllegalArgumentException
@author	作者	@author 码上学
@since	从哪个版本开始有	@since 25
@see	关联参考	@see Calculator

用 javadoc 生成文档

文档注释不是摆设。JDK 自带一个 javadoc 工具，能把这些注释抽出来，生成一套网页版说明。

在命令行进入文件所在目录，执行：

javadoc Calculator.java

它会生成一堆 .html 文件，用浏览器打开 index.html，就是一份排版好的 API 手册。大项目的官方文档，基本都是这么生成的。

注释写什么，不写什么

新手最容易犯的错，是把代码「翻译」一遍当注释：

age++;   // age 加 1

这句注释毫无信息量——代码本身已经说了 age 加 1。写这种注释纯属凑数。

好的注释解释为什么，而不是重复是什么：

// 超过 60 岁走老年优惠价，这是产品定的规则
if (age > 60) {
    price = price * 0.8;
}

临时屏蔽一段代码

调试时，你可能想先「关掉」某几行代码，看看去掉它们程序还报不报错。这时用多行注释把那段包起来最方便：

public class ToggleDemo {
    public static void main(String[] args) {
        int a = 1;
        /*
        int b = a / 0;   // 这行会抛异常，先屏蔽掉排查
        System.out.println(b);
        */
        System.out.println(a);
    }
}

注释会过期，比没有更坑

代码改了，注释没改，是最隐蔽的坑。比如下面这样：

// 计算总价（含税）
int total = price + shipping;   // 其实已经不含税了，注释却还写着含税

读代码的人信了注释，按「含税」去理解逻辑，结果全错。注释不是写完就完事，它和代码一样需要维护。 改代码时，顺手把相关注释改对，是基本素养。

中文还是英文注释

初学者用中文写注释完全没问题，能把思路说清楚最重要。等工作进了团队，再按团队的约定来——很多公司要求英文注释，那是为了跨国协作；但规则是团队定的，不是 Java 定的。

三种注释放一起看

把今天学的三种写法放进同一个文件，对比着感受一下：

/**
 * 学生类，演示三种注释的写法。
 */
public class Student {
    // 单行注释：姓名
    private String name;

    /*
     * 多行注释：
     * 年龄字段，默认 0
     */
    private int age;

    public void show() {
        System.out.println(name + "：" + age);
    }
}

文档注释的即时好处

回到上一章说的 IDE。你给方法写了文档注释后，在别处调用这个方法时，鼠标悬上去，IDE 会直接把 @param、@return 的说明弹出来。

等于你写注释的同时，顺手给队友（和未来的自己）做了一份随时能看的操作手册。这正是文档注释比普通注释多出的价值。

注释不是越多越好

提醒一句：注释是辅助，不是越多越安全。满屏注释反而掩盖了代码本身。

真正清晰的代码，变量名、方法名起得妥帖，读起来就像句子，注释可以很少。注释应该填补代码表达不了的那部分——也就是意图和原因。

小结

注释写给人和未来的自己看，编译器会直接忽略，不影响运行。

三种写法：单行 //、多行 /* */（不能嵌套）、文档注释 /** */。

文档注释用 @param、@return 等标签描述类和方法，可用 javadoc 工具生成网页版 API 文档。

注释要写「为什么」，别把代码翻译一遍凑数。