歡迎光臨
每天分享高質量文章

在 Java 中正確使用註釋

(點選上方公眾號,可快速關註)


來源:ImportNew – 進林

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

 

*/

在你需要使用註釋的時候儘量使用單行註釋。

什麼時候使用多行註釋

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

看完本文有收穫?請轉發分享給更多人

關註「ImportNew」,提升Java技能

贊(0)

分享創造快樂