Java 注释：单行注释、多行注释与 Javadoc

注释有什么用

注释是源代码中被 Java 编译器完全忽略的文字。它永远不会成为运行中程序的一部分，纯粹是写给读代码的人看的。你用注释来解释为什么某件事要这样做、留下提醒，或者在不删除代码的情况下暂时禁用它。

Java 有三种注释：单行注释（//）、多行块注释（/* */）和 Javadoc 文档注释（/** */）。它们的基本作用相同，都会在编译时被忽略，但各有各的使用场景。

单行注释

两个斜杠（//）开始一段注释，一直延续到当前行的末尾。编译器会跳过从 // 到换行之间的所有内容。

public class Main {
    public static void main(String[] args) {
        // Print a greeting to the console
        System.out.println("Hello, Java!");

        int score = 90; // a comment can also sit after code
        System.out.println(score);
    }
}

注意第二条注释和真正的代码在同一行。// 之前的内容照常运行，只有它后面的部分被忽略。这是写简短说明时最常用的注释方式。

多行块注释

当说明跨越好几行时，块注释比在每一行前面加 // 更整洁。块注释以 /* 开始，以 */ 结束。两者之间的所有内容，无论多少行，都会被忽略。

public class Main {
    public static void main(String[] args) {
        /*
         * This program shows a block comment.
         * The leading asterisks on each line are just a
         * convention for readability - they are not required.
         */
        System.out.println("Block comments are handy.");
    }
}

左侧对齐的一列 * 只是一种风格约定，不是规则。真正起作用的只有开头的 /* 和结尾的 */。

注释掉代码

在试验时，用注释禁用代码而不删除它，是标准做法。单行用 //，要一次关掉好几行就用块注释。

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

运行它，你只会看到两行“runs”被打印出来。被注释掉的 println 调用对编译器来说是不可见的。

一个常见的陷阱：块注释不能嵌套。第一个 */ 就会结束注释，不管前面出现过多少个 /*。所以你不能把一个 /* ... */ 块包在另一个 /* ... */ 块里：内层的 */ 会结束整个注释，剩下的部分就成了语法错误。如果要禁用一段本身已经包含块注释的代码，改为在每一行前面加 //（大多数编辑器用一个快捷键就能做到）。

Javadoc 文档注释

Javadoc 注释看起来像块注释，但以 /** 开头，有两个星号。它用来为类、方法或字段编写文档，紧挨着写在被描述对象的上方。javadoc 工具会把这些注释转换成可浏览的 HTML API 文档，IDE 也会在鼠标悬停时显示它们。

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

@param、@return 和 @throws 标签是工具能识别的结构化字段。对编译器来说，这仍然只是一段被忽略的注释，它的价值完全在于生成的文档，以及给其他开发者（还有六个月后的你）提供的 IDE 提示。

好注释与无用注释

注释应该解释代码本身说不清的东西。只是把代码复述一遍的注释只会添乱，而且随着代码改动往往会过时。

// Bad: just repeats what the code obviously does
int i = i + 1; // add one to i

// Better: explains the reason, which the code can't show
retries++; // back off and retry; the API is rate-limited at 5 req/sec

尽量通过清晰的命名和结构让代码本身易读，把注释留给“为什么”：意图、取舍、边界情况，以及相关背景的链接。如果你发现自己在写注释来解释一行令人困惑的代码，这往往说明你应该重命名变量或提取一个方法。

下一步：变量

现在你已经会给代码加注释了，下一个基础知识是在代码中存储数据。下一页讲变量：如何声明变量、变量存放的类型，以及 Java 作为静态类型语言所强制执行的规则。