在Java中正確使用注釋
2018-07-20 來源：編程學(xué)習(xí)網(wǎng)
Java提供了3種類型的注釋：
單行注釋（C++風(fēng)格）
在Java中最簡單的注釋是單行注釋。它以兩個正斜杠開始并到行尾結(jié)束。例如：
// this is a single-line comment x = 1; // a single-line comment after code
多行注釋（C風(fēng)格）
Java同樣提供跨越多行的注釋類型。這種類型的注釋以緊跟著一個星號的正斜杠開始，并以緊跟著一個正斜杠的星號結(jié)束。這種類型注釋的開始和結(jié)束分界符可以在同一行里也可以在不同的行上。例如：
/* This is a c-style comment */
/* This is also a
c-style comment, spanning
multiple lines */
注意：C風(fēng)格的注釋不可以嵌套使用。比如下面的用法：
/* A comment looks like /* This is a comment */ blah blah blah */
上面的用法會造成語法錯誤，因為Java編譯器只把第一個 */ 當(dāng)做注釋來處理。（編譯器認(rèn)為注釋在第一個“*/”就結(jié)束了）。
你可以在多行注釋里嵌入單行注釋：
/* This is a single-line comment:
// a single-line comment
*/
以及在單行注釋里使用多行注釋：
// /* this is // a multi-line // comment */
文檔注釋
文檔注釋是一種與多行注釋很類似的特殊注釋，它可以用來為你的源代碼產(chǎn)生外部文檔。這種注釋以緊跟著兩個星號的正斜杠開始，并以緊跟著一個正斜杠的星號結(jié)束。例如：
/** This is a documentation comment */
/** This is also a
documentation comment */
這里有一些關(guān)于文檔注釋的重要事情要注意：
- javadoc文檔生成器會把文檔注釋里的所有文本都添加到一個HTML段落里。這意味著，在文檔注釋里的任意文本都會被格式化為一個段落；空格和換行符會被忽略。如果你想要特殊的格式，你必須要在文檔注釋里使用HTML標(biāo)簽。
- 如果文檔注釋以超過兩個的星號開始，那么javadoc就認(rèn)為這些星號是用來在源碼里創(chuàng)建一個“框”框住注釋的，并忽略多余的星號。例如：
/********************************** 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””文本。
- 常見的用法如下：
/****************************************** ... ******************************************/
該用法是為了突出注釋。要注意的是，這屬于文檔注釋（即使這不是你所想的那樣），并會在產(chǎn)生的文檔里出現(xiàn)注釋的內(nèi)容。
什么時候使用文檔注釋
你（至少）應(yīng)該在任意的公有類、接口、方法和源碼里的類或?qū)嵗兞壳懊媸褂梦臋n注釋。這樣可以讓javadoc針對代碼產(chǎn)生簡單的文檔，它列出了公共實體 和每個實體的簡要說明。你同樣可以在非公共方法前面使用文檔注釋，不過需要使用一個javadoc選項來它們產(chǎn)生文檔。相比于公有實體，在非公有實體上使 用文檔注釋顯得沒那么重要（它的接口不會暴露出來……）。但如果你要注釋代碼，你同樣可以使用文檔注釋。
什么時候使用單行注釋
任意時候都可以！
關(guān)于注釋，我有一個簡單的建議，在你想寫常規(guī)注釋（不是用來描述類、接口、方法或者變量的文檔注釋）的時候可以使用單行注釋。
為什么？因為你可以輕易地使用多行注釋去“注釋掉”你的代碼段（“注釋掉代碼”意味著把一段代碼的詞法狀態(tài)變?yōu)橐欢巫⑨�，讓編譯器忽略這段代碼）。舉個例子：
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 */
或者分解或刪除已存在的注釋的“結(jié)束注釋”分解符：
/* 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 */
在你需要使用注釋的時候盡量使用單行注釋，不要寫無用的注釋。
你也可以看看之前發(fā)布的9個最有趣的代碼注釋，盡管它是搞笑的。
什么時候使用多行注釋
閱讀了上面的內(nèi)容后，這個問題變得很明顯了。只使用多行注釋來注釋代碼段，不要用以其他目的。
標(biāo)簽： 代碼
版權(quán)申明：本站文章部分自網(wǎng)絡(luò)，如有侵權(quán)，請聯(lián)系：west999com@outlook.com
特別注意：本站所有轉(zhuǎn)載文章言論不代表本站觀點！
本站所提供的圖片等素材，版權(quán)歸原作者所有，如需使用，請與原作者聯(lián)系。
