在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个最有趣的代码注释，尽管它是搞笑的。

什么时候使用多行注释

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