在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個最有趣的程式碼註釋，儘管它是搞笑的。

什麼時候使用多行註釋

閱讀了上面的內容後，這個問題變得很明顯了。只使用多行註釋來註釋程式碼段，不要用以其他目的。