Java 注释总结

该图片由Nimrod Oren在Pixabay上发布

你好，我是看山。

在 Java 的编写过程中我们需要对一些程序进行注释，除了自己方便阅读，更为别人更好理解自己的程序，所以我们需要进行一些注释，可以是编程思路或者是程序的作用，总而言之就是方便自己他人更好的阅读。

1 开篇

在程序开发过程中，经常会遇到修改其他人代码的情况。这时候手里的代码会有这么几种情况：

  • 有条理，通俗易懂；
  • 没有条理，通俗易懂；
  • 有条理，高深；
  • 没有条理，高深。

一般说来，遇到前两种的比较幸运，至少通过浏览一遍代码，就能知道需要修改哪些地方，如何修改。但遇到后两种情况，尤其第 4 种情况，绝对是云里雾里，极有可能自己重新写了。
这就出现了几个问题：

  1. 如何高质量的进行开发和维护工作；
  2. 如何在第一次接触代码时迅速了解这段代码的意图及功能；
  3. 如何避免冗余或杂乱不堪的代码。

程序中的注释是软件设计者/软件开发人员与程序阅读者之间通信的重要手段，良好的规范及良好的执行规范对于软件本身和软件开发人员尤为重要。在软件的生命周期中，良好的注释可以改善代码的可读性，能够使开发人员尽快理解前辈遗留的代码（其中不乏使用了巧妙的可读性差的算法）；再者，能够最大限度的规范代码，提高团队合作效率；其次，长期遵循编码规范，能够养成开发人员良好的编码习惯及更加严谨的思维；并且，在敏捷开发思想中甚至提出将注释转为代码的概念。

2 Java 注释方法及格式

2.1 单行注释（或短注释）：//

单行注释起源于 C++，以一个“//”起头，表示这一行的所有内容都是注释。这种类型的注释更常用，因为它书写时更方便。没有必要在键盘上寻找“/”，再寻找“*”（只需按同样的键两次），而且不必在注释结尾时加一个结束标记。下面便是这类注释的一个例子：

// 这是一条单行注释

2.2 块注释：/* … */

这种注释是传统的 C 语言风格的注释，以一个“/”起头，随后是注释内容，并可跨越多行，最后用一个“/”结束。这种注释可以注释若干行，通常用于提供文件、方法、数据结构等的意义与用途的说明，或者算法的描述。一般位于一个文件或者一个方法的前面，起到引导的作用，也可以根据需要放在合适的位置。许多程序员在连续注释内容的每一行都用一个“*”开头，所以经常能看到象下面这样的内容：

/*
 * 这里是
 * 注释内容，
 * 跨越多行。
 */

注：块注释不会出现在 HTML 文档中。所以下面的注释和上面的没有区别：

/* 这里是注释内容，
跨越多行。*/

2.3 文档注释：/** … */

/**
 * 注释内容
 */

在软件开发过程中，除了编写程序之外，还应该实现程序的文档化。对于程序的文档化，最大的问题莫过于对文档的维护。若文档与代码分离，那么每次修改代码后都要改变文档，对于大多数开发人员都是相当麻烦的事（好不容易修改好了代码，谁还有闲心再找到文档并修改文档）。最简单的解决办法就是将文档与代码“链接”起来。在 Java 中，很贴心的设计了将代码与文档放置在同一个文件。同时，为了让文档与代码整齐划一，增加了特殊的注释语法，用于标记特殊的文档；为了提取注释并以有意义的方式展现，增加了一个工具（小伙伴们一定都知道说的是 javac）。
文档注释必须写在/** … */中，使用嵌入的 HTML 或文档标记两种方式使用 javac。有三种类型的注释文档，它们对应于位于注释后面的元素：类、变量或者方法。也就是说，一个类注释正好位于一个类定义之前；变量注释正好位于变量定义之前；一个方法定义正好位于一个方法定义的之前。而且，在默认情况下，javac 只能为 public 和 protected 成员处理文档注释，忽略 private 成员的注释（可以通过-private 标记包含 private 成员）。

2.3.1 嵌入 HTML

可以像绘制 HTML 页面一样编写文档，因为 javac 最终生成 HTML 页面，所以只要是正确的 HTML 标签，都能够使用（除了像

这种标题标签，因为 javac 会插入自己的标题，容易引起冲突）。如下例（摘自《Java 编程思想》)：

/**
 * <pre>
 * System.out.println(new Date());
 * </pre>
 * 
 * 您<em> 甚至</em>可以插入一个列表：
 * <ol>
 * <li> 项目一
 * <li> 项目二
 * <li> 项目三
 * </ol>
 */

2.3.2 @see: 引用其他类

这个标记允许我们引用其他类的文档，javac 会生成相应的 HTML，直接链接到其他文档中。格式如下：

@see 类名
@see 完整类名
@see 完整类名#方法名

每一格式都会在生成的文档里自动加入一个超链接的“See Also ”条目。(javadoc 不会检查我们指定的超链接，不会验证它们是否有效。)

2.3.3 类文档标记

除了嵌入 HTML 和@see 引用，类文档注释还可以包括版本信息、作者的标记：

@version 版本信息

“版本信息”代表任何适合作为版本说明的资料。若在 javadoc 命令行使用了“-version”标记，就会从生成的 HTML 文档里提取出版本信息。

@author 作者信息

“作者信息”包括您的姓名、电子函件地址或者其他任何适宜的资料。若在 javadoc 命令行使用了“-author”标记，就会专门从生成的 HTML 文档里提取出作者信息。可为一系列作者使用多个这样的标记，但它们必须连续放置。全部作者信息会一起存入最终 HTML 代码的单独一个段落里。

2.3.4 变量文档标记

变量文档只能包括嵌入的 HTML 以及@see 引用。

2.3.5 方法文档标记

除嵌入 HTML 和@see 引用之外，方法还允许使用针对参数、返回值、异常的文档标记。

@param 参数名 说明

“参数名”是指参数列表内的标识符，而“说明”代表一些可延续到后续行内的说明文字。一旦遇到一个新文档标记，就认为前一个说明结束。可使用任意数量的说明，每个参数一个。

@return 说明

“说明”是指返回值的含义。它可延续到后面的行内。

@exception 完整类名 说明

“完整类名”明确指定了一个违例类的名字，它是在其他某个地方定义好的。而“说明”（同样可以延续到下面的行）告诉我们为什么这种特殊类型的违例会在方法调用中出现。

@throws 完整类名 说明

与@exception 同义。

@deprecated

该标记用于指出一些旧功能已由改进过的新功能取代。该标记的作用是建议用户不必再使用一种特定的功能，因为未来改版时可能摒弃这一功能。若将一个方法标记为@deprecated，则使用该方法时会收到编译器的警告。
注：Java 带有的注释标记不止这些，这里只是介绍几个比较常用的注释标记。

3 注释技巧-算是抛砖引玉

注释的目的主要有三点：

  1. 代码整洁；
  2. 迅速理解代码作用及原理；
  3. 形成文档。

所以根据这几年的经验，总结几条技巧，算是抛砖引玉。

  1. 在代码中加入必要的空行及空白字符，可以使代码分段清晰。对注释提供规范的缩进，协调美观。
  2. 在代码较长或多重嵌套的情况下，应该在一些段落结束处增加比较的注释提示。
  3. 在注释与注释分隔符之间用一个空格隔开，可以比较容易找到注释。
  4. 绝对不要给注释添加边框，如果增加了，这将是噩梦的开始。
  5. 注释长度最好不大于 80~120 字符，否则在窄屏中查看起来很费劲。

利用块注释作为代码的开关：
下面代码中打印 1

//*
 System.out.println(1);
/*/
 System.out.println(2);
//*/

下面代码中打印 2

/*
 System.out.println(1);
/*/
 System.out.println(2);
//*/

对于程序中有两段代码需要切换的情况，这个还是很方便的，只需要在第一行增加或删除“/”即可。（当然，很多人喜欢全选，通过快捷键在每行使用//注释。Eclipse 和 Intellij IDEA 中使用 ctrl+/。)

你好，我是看山，10 年老猿，开源贡献者。游于码界，戏享人生。关注公众号：看山的小屋，领取学习资料。

个人主页：https://www.howardliu.cn
个人博文：Java 注释总结
CSDN 主页：https://blog.csdn.net/liuxinghao
CSDN 博文：Java 注释总结