2.10　注释

在代码中加入注释有助于记录在编写代码时的瞬间灵感，注释更大的作用是提醒自己，以及告诉其他程序员你所写的代码的作用是什么。

与大多数程序设计语言一样，Java中的注释也不会出现在编译后的代码中。

2.10.1　传统注释

Java完全借鉴了C++的注释风格：

第一种方法用于单行注释，从双斜杠（//）开始到本行结束的所有字符均作为注释而被编译器忽略。

第二种方法用于多行注释，从“/*”开始，直到遇到第一个“*/”为止，它们之间的内容均为注释而被编译器忽略。

至于使用哪种注释风格，完全取决于读者的喜好。有时我们在开发一些项目或者使用一些特殊的文档生成工具时，注释的风格会受到一定的约束，不过这是一种规范的体现，接受这种规范能使得协同工作更加顺畅。

2.10.2　JavaDoc注释

如果读者看过Java的API文档，你会看到包的说明、类的说明、方法的说明等，而这些内容可以以注释的方式写在我们的源程序中，然后通过JDK中的javadoc工具来生成网页版的说明文档。这种注释以 /** 开始，以 */ 结束，我们称之为JavaDoc注释。

下面是一个包含了JavaDoc注释的类，如代码2.31所示。

JavaDoc注释以“/**”开始并独占一行，以“*/”结尾。至于中间各行是否要在开头添加一个星号（*），并没有强制要求，而是由开发者自行决定的，当然，目前绝大多数开发者会采用这种风格。在JavaDoc注释里，有以“@”字符开头的标记，这些标记修饰后面的内容为标记单词的含义。如：@auther sunxin 说明作者是sunxin。下面介绍一些常用的标签：

读者可以打开命令提示符窗口，输入下面的命令来生成JavaDoc文档。

参数-d指定输出文件的目标目录，参数-author和-version是告诉javadoc在生成的文档中包含@author和@version字段。

你会看到在当前目录的doc子目录下生成了很多文件，打开index.html，如图2-13所示。

要查看javadoc命令的详细用法，可以使用-help参数来执行该命令，如下所示。

提示：Java 9对JavaDoc文档作出了一些改进，执行javadoc命令时带上-html5参数，可以让生成的文档支持HTML 5，同时在文档中还会生成一个搜索框，便于我们查找类、方法等。而目前JDK版本的javadoc工具默认使用HTML 5来生成文档，所以无需添加-html5参数。