在Java中正确使用注释

Java提供了3种类型的注释：

单行注释（C++风格）

在Java中最简单的注释是单行注释。它以两个正斜杠开始并到行尾结束。例如：

// this is a single-line comment

x = 1; // a single-line comment after code

多行注释（C风格）

Java同样提供跨越多行的注释类型。这种类型的注释以紧跟着一个星号的正斜杠开始，并以紧跟着一个正斜杠的星号结束。这种类型注释的开始和结束分界符可以在同一行里也可以在不同的行上。例如：

/* This is a c-style comment */

/*  This is also a

    c-style comment, spanning

    multiple lines */

注意：C风格的注释不可以嵌套使用。比如下面的用法：

/* A comment looks like

   /* This is a comment */

   blah blah blah

 */

上面的用法会造成语法错误，因为Java编译器只把第一个 */ 当做注释来处理。（编译器认为注释在第一个“*/”就结束了）。

你可以在多行注释里嵌入单行注释：

/* This is a single-line comment:

    // a single-line comment

 */

以及在单行注释里使用多行注释：

// /* this is

//    a multi-line

//    comment */

文档注释

文档注释是一种与多行注释很类似的特殊注释，它可以用来为你的源代码产生外部文档。这种注释以紧跟着两个星号的正斜杠开始，并以紧跟着一个正斜杠的星号结束。例如：

/** This is a documentation comment */

/** This is also a

    documentation comment */

这里有一些关于文档注释的重要事情要注意：

• javadoc文档生成器会把文档注释里的所有文本都添加到一个HTML段落里。这意味着，在文档注释里的任意文本都会被格式化为一个段落；空格和换行符会被忽略。如果你想要特殊的格式，你必须要在文档注释里使用HTML标签。

• 如果文档注释以超过两个的星号开始，那么javadoc就认为这些星号是用来在源码里创建一个“框”框住注释的，并忽略多余的星号。例如：

/**********************************

   This is the start of a method

**********************************/

该注释仅保留“This is the start of a method”文本。

• javadoc会忽略文档注释里处于行首的星号。例如：

/***************************************

 * This is a doc comment

 * on multiple lines that I want to stand

 * out in source code, looking "neat"

 ***************************************/

该注释仅保留“This is a doc comment on multiple lines that I want to stand out in source code, looking “neat””文本。

• 常见的用法如下：

/******************************************

   ...

 ******************************************/

该用法是为了突出注释。要注意的是，这属于文档注释（即使这不是你所想的那样），并会在产生的文档里出现注释的内容。

什么时候使用文档注释

你（至少）应该在任意的公有类、接口、方法和源码里的类或实例变量前面使用文档注释。这样可以让javadoc针对代码产生简单的文档，它列出了公共实体 和每个实体的简要说明。你同样可以在非公共方法前面使用文档注释，不过需要使用一个javadoc选项来它们产生文档。相比于公有实体，在非公有实体上使 用文档注释显得没那么重要（它的接口不会暴露出来……）。但如果你要注释代码，你同样可以使用文档注释。

什么时候使用单行注释

任意时候都可以！

关于注释，我有一个简单的建议，在你想写常规注释（不是用来描述类、接口、方法或者变量的文档注释）的时候可以使用单行注释。

为什么？因为你可以轻易地使用多行注释去“注释掉”你的代码段（“注释掉代码”意味着把一段代码的词法状态变为一段注释，让编译器忽略这段代码）。举个例子：

x = 1;   /* set x to 1 */

y = 2;   /* set y to 2 */

f(x, y); /* call f with x and y */

要把上面三行代码注释掉，你可能需要在每一行的前面使用单行注释：

// x = 1;   /* set x to 1 */

// y = 2;   /* set y to 2 */

// f(x, y); /* call f with x and y */

或者在还没有加注释的地方加上多行注释：

/* x = 1;  */ /* set x to 1 */

/* y = 2;  */ /* set y to 2 */

/* f(x, y);*/ /* call f with x and y */

或者分解或删除已存在的注释的“结束注释”分解符：

/*

x = 1;   /* set x to 1 * /

y = 2;   /* set y to 2 * /

f(x, y); /* call f with x and y * /

*/

这些用法都糟糕透了。如果原始代码使用下面的注释，那么事情就好办多了：

x = 1;   // set x to 1

y = 2;   // set y to 2

f(x, y); // call f with x and y

如此一来，只需使用多行注释把代码围起来你就可以轻松把它注释掉：

/*

x = 1;   // set x to 1

y = 2;   // set y to 2

f(x, y); // call f with x and y

*/

在你需要使用注释的时候尽量使用单行注释，不要写无用的注释。

你也可以看看之前发布的9个最有趣的代码注释，尽管它是搞笑的。

什么时候使用多行注释

阅读了上面的内容后，这个问题变得很明显了。只使用多行注释来注释代码段，不要用以其他目的。