《JAVA代码规范》（四）通用代码格式 - 注释(2.7)

2.7      注释

Java程序有两类注释：实现注释(implementation comments)和文档注释(document comments)。实现注释是那些在C++中见过的，使用/*...*/和//界定的注释。文档注释(被称为"doc comments")是Java独有的，并由/**...*/界定。文档注释可以通过javadoc工具转换成HTML文件。

注意：频繁的注释有时反映出代码的低质量。当你觉得被迫要加注释的时候，考虑一下重写代码使其更清晰。

2.7.1        注释约定

?         注释应该增加代码的清晰度。代码注释的目的是要使代码更易于被同时参与程序设计的开发人员以及其他后继开发人员理解。

?         避免使用装饰性内容，也就是说，不要使用象广告横幅那样的注释语句。典型的是用星号将他们的内部注释圈起来。这只是在大量浪费时间，并不能给最终的产品增加丝毫价值。

?         保持注释的简洁。最好的注释应该是简单明了的注释。注释不必洋洋洒洒，只需提供足够的信息，使别人能够理解你的代码。

?         先写注释，后写代码。写代码注释的最好方法是在写代码之前就写注释。这使你在写代码之前可以想想代码的功能和运行。而且这样确保不会遗漏注释。另一种方法是边写代码边写注释。因为注释可以使代码更易理解，所以在程序开发的过程中，也可以利用这一点。如果打算花些时间写注释，那么至少你应从这个过程中获得些什么 。

?         注释信息不仅要包括代码的功能，还应给出原因。例如，下面例子中的代码显示金额在$1,000 以上（包括 $1,000）的定单可给予 5% 的折扣。为什么要这样做呢？难道有一个商业法则规定大额定单可以得到折扣吗？这种给大额定单的特殊是有时限的呢，还是一直都这样？最初的程序设计者是否只是由于慷慨大度才这样做呢？除非它们在某个地方（或者是在源代码本身，或者是在一个外部文档里）被注释出来，否则你不可能知道这些。

例：

if (grandTotal >= 1000.00) {

grandTotal = grandTotal * 0.95;

}

2.7.2        实现注释的格式

程序可以有4种实现注释的风格：块(block)、单行(single-line)、尾端(trailing)和行末(end-of-line)。

?        块注释

    块注释通常用于提供对文件，方法，数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方，比如方法内部。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。块注释之首应该有一个空行，用于把块注释和代码分割开来，比如：

/*
 * Here is a block comment.
 */

块注释可以以/*-开头，这样indent(1)就可以将之识别为一个代码块的开始，而不会重排它。

/*
 * Here is a block comment with some very special
 * formatting that I want indent(1) to ignore.
 *
 *    one
 *        two
 *            three
 */

?        单行注释

短注释可以显示在一行内，并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完，就该采用块注释(参见"块注释")。单行注释之前应该有一个空行。以下是一个Java代码中单行注释的例子：

if (condition) {
    /* Handle the condition. */
    ...
  }

?        尾端注释

极短的注释可以与它们所要描述的代码位于同一行，但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中，它们应该具有相同的缩进。以下是一个Java代码中尾端注释的例子：

if (a == 2) {
     return TRUE;              /* special case */
 } else {
     return isPrime(a);        /* works only for odd a */
 }

?        行末注释

注释界定符"//"，可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本；然而，它可以用来注释掉连续多行的代码段。以下是所有三种风格的例子：

if (foo > 1) {
 
     // Do a double-flip.
     ...
 }
 else {
     return false;          // Explain why here.
 }
 
 //if (bar > 1) {
 //
 //    // Do a triple-flip.
 //    ...
 //}
 //else {
 //    return false;
 //}

2.7.3        文档注释

文档注释描述Java的类、接口、构造器，方法，以及字段(field)。每个文档注释都会被置于注释定界符/**...*/之中，一个注释对应一个类、接口或成员。该注释应位于声明之前：

 /**

  * The Example class provides ...

  */

 public class Example { ...

注意顶层(top-level)的类和接口是不缩进的，而其成员是缩进的。描述类和接口的文档注释的第一行(/**)不需缩进；随后的文档注释每行都缩进1格(使星号纵向对齐)。成员，包括构造函数在内，其文档注释的第一行缩进4格，随后每行都缩进5格。

若你想给出有关类、接口、变量或方法的信息，而这些信息又不适合写在文档中，则可使用实现块注释或紧跟在声明后面的单行注释。例如，有关一个类实现的细节，应放入紧跟在类声明后面的实现块注释中，而不是放在文档注释中。

文档注释不能放在一个方法或构造器的定义块中，因为Java会将位于文档注释之后的第一个声明与其相关联。

2.7.4        快速浏览 javadoc

javadoc 的程序可以处理 Java 的源代码文件，并且为 Java 程序产生 HTML 文件形式的外部注释文档。Javadoc 支持一定数目的标记，标识注释文档中各段起始位置的保留字。详情请参考J2SDK javadoc 文档。