Java提供了3種類型的注釋

例如：

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

多行注釋(C風(fēng)格)

Java同樣提供跨越多行的注釋類型。這種類型的注釋以緊跟著一個(gè)星號(hào)的正斜杠開(kāi)始，并以緊跟著一個(gè)正斜杠的星號(hào)結(jié)束。這種類型注釋的開(kāi)始和結(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 */ 

上面的用法會(huì)造成語(yǔ)法錯(cuò)誤，因?yàn)镴ava編譯器只把***個(gè) */ 當(dāng)做注釋來(lái)處理。(編譯器認(rèn)為注釋在***個(gè)“*/”就結(jié)束了)。

你可以在多行注釋里嵌入單行注釋：

/* This is a single-line comment: // a single-line comment */ 

以及在單行注釋里使用多行注釋：

// /* this is // a multi-line // comment */ 

文檔注釋

文檔注釋是一種與多行注釋很類似的特殊注釋，它可以用來(lái)為你的源代碼產(chǎn)生外部文檔。這種注釋以緊跟著兩個(gè)星號(hào)的正斜杠開(kāi)始，并以緊跟著一個(gè)正斜杠的星號(hào)結(jié)束。例如：

/** This is a documentation comment */ /** This is also a documentation comment */ 

這里有一些關(guān)于文檔注釋的重要事情要注意：

javadoc文檔生成器會(huì)把文檔注釋里的所有文本都添加到一個(gè)HTML段落里。這意味著，在文檔注釋里的任意文本都會(huì)被格式化為一個(gè)段落;空格和換行符會(huì)被忽略。如果你想要特殊的格式，你必須要在文檔注釋里使用HTML標(biāo)簽。

如果文檔注釋以超過(guò)兩個(gè)的星號(hào)開(kāi)始，那么javadoc就認(rèn)為這些星號(hào)是用來(lái)在源碼里創(chuàng)建一個(gè)“框”框住注釋的，并忽略多余的星號(hào)。例如：

該注釋僅保留“This is the start of a method”文本。

javadoc會(huì)忽略文檔注釋里處于行首的星號(hào)。例如：

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

常見(jiàn)的用法如下：

該用法是為了突出注釋。要注意的是，這屬于文檔注釋(即使這不是你所想的那樣)，并會(huì)在產(chǎn)生的文檔里出現(xiàn)注釋的內(nèi)容。

什么時(shí)候使用文檔注釋

你(至少)應(yīng)該在任意的公有類、接口、方法和源碼里的類或?qū)嵗兞壳懊媸褂梦臋n注釋。這樣可以讓javadoc針對(duì)代碼產(chǎn)生簡(jiǎn)單的文檔，它列出了公共實(shí)體 和每個(gè)實(shí)體的簡(jiǎn)要說(shuō)明。你同樣可以在非公共方法前面使用文檔注釋，不過(guò)需要使用一個(gè)javadoc選項(xiàng)來(lái)它們產(chǎn)生文檔。相比于公有實(shí)體，在非公有實(shí)體上使 用文檔注釋顯得沒(méi)那么重要(它的接口不會(huì)暴露出來(lái)……)。但如果你要注釋代碼，你同樣可以使用文檔注釋。

什么時(shí)候使用單行注釋

任意時(shí)候都可以!

關(guān)于注釋，我有一個(gè)簡(jiǎn)單的建議，在你想寫常規(guī)注釋(不是用來(lái)描述類、接口、方法或者變量的文檔注釋)的時(shí)候可以使用單行注釋。

為什么?因?yàn)槟憧梢暂p易地使用多行注釋去“注釋掉”你的代碼段(“注釋掉代碼”意味著把一段代碼的詞法狀態(tài)變?yōu)橐欢巫⑨專尵幾g器忽略這段代碼)。舉個(gè)例子：

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 */ 

或者在還沒(méi)有加注釋的地方加上多行注釋：

/* 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 

如此一來(lái)，只需使用多行注釋把代碼圍起來(lái)你就可以輕松把它注釋掉：

/* x = 1; // set x to 1 y = 2; // set y to 2 f(x, y); // call f with x and y */ 

在你需要使用注釋的時(shí)候盡量使用單行注釋。

什么時(shí)候使用多行注釋

閱讀了上面的內(nèi)容后，這個(gè)問(wèn)題變得很明顯了。只使用多行注釋來(lái)注釋代碼段，不要用以其他目的。