JAVA代码规范笔记（上） - JAVA

ock comment. */
块注释可以以 /*-开头，这样indent(1)就可以识别到它是一个块注释的开头，而不会去重格式化它。

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

注意：如果你不使用indent(1)，你就不必要在你的代码中使用/*-，或为其他人可能对你的代码运行indent(1)作出其他的让步。
13、单行注释短的注释可以出现在一行内，并与其后面的代码有一样的缩进层级。如果一个注释无法在一行内写完，就应该使用块注释格式。一个单行注释前应该有一个空行。下面是Java代码里的单行注释的例子：

if (condition) {

    /* Handle the condition. */
    ...
}

14、尾端注释非常短的注释可以出现在其描述的代码的同一行，但应该有足够的空白来分开代码与注释。如果有超过一个的短注释出现在一大块代码中，它们应该被缩进到同一个tab setting中（不会翻译，原文是they should all be indented to the same tab setting，大概意思是缩进到这些注释能对齐）。避免在每一行可执行代码都加上一个尾端注释的这种汇编语言风格的注释。下面是Java代码尾端注释的一个例子：

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

15、行末注释注释分隔符“//”开头的是不断换行的注释。它可以用来注释掉整行或一行中的一部分。它一般不用于连续多行的文本注释，但可以被用来注释掉连续多行的代码段。下面是所有三种风格的例子：

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

//if (bar > 1) {
//
//    // Do a triple-flip.
//    ...
//}
//else
//    return false;

16、文档注释若想了解更多详情，参见“How to Write Doc Comments for Javadoc”，其中包含了文档注释标记的信息（@return,@param,@see）： http://java.sun.com/products/jdk/javadoc/writingdoccomments. html 关于文档注释和javadoc的更多信息，参见javadoc主页： http://java.sun.com/products/jdk/javadoc/
文档注释描述Java的类、接口、构造器、方法和字段。每个文档注释都置于注释分隔符/**...*/中，每个API对应一个注释。这个注释应该只出现在声明之前：

/**
 * The Example class provides ...
 */
class Example { ...

注意类和接口是不缩进的，而它的成员是缩进的。类和接口的文档注释的第一行（/**）是不缩进的，其后的文档注释行的都各有一个空格的缩进（使星号垂直对齐）。成员，包括构造方法，其文档注释的第一行是4个空格的缩进，其后是缩进5个空格。如果你需要给出有关类、接口、变量或方法的信息，而这些信息又不适合出现在文档中，可以在紧跟在声明之后使用块注释或单行注释。例如一个类实现的细节，就应该在紧跟在类声明之后的块注释中，而不是在这个类的文档注释中。文档注释不应该被放在方法或构造器的定义块中，因为Java会将文档注释与其后面的第一个声明进行关联。

JAVA代码规范笔记（上）(二)