一般情況下，源程序有效注釋量必須在30％以上。注釋的原則是有助于對(duì)程序的閱讀理解，在該加的地方都加了，注釋不宜太多也不能太少，注釋語(yǔ)言必須準(zhǔn)確、易懂、簡(jiǎn)潔。可以用注釋統(tǒng)計(jì)工具來(lái)統(tǒng)計(jì)。

• 類和接口的注釋：類和接口必須寫注釋。該注釋放在 package 關(guān)鍵字之后，class 或者 interface 關(guān)鍵字之前。
  說(shuō)明：方便JavaDoc收集。
  示例：

package com.huawei.msg.relay.comm;
/**
 * 注釋內(nèi)容
 */
public class CommManager

• 類和接口的注釋內(nèi)容：類的注釋主要是一句話功能簡(jiǎn)述、功能詳細(xì)描述。
  格式：

/**
 * 〈一句話功能簡(jiǎn)述〉
 * 〈功能詳細(xì)描述〉
*/

說(shuō)明：描述部分說(shuō)明該類或者接口的功能、作用、使用方法和注意事項(xiàng)。
示例：

/**
 * LogManager 類集中控制對(duì)日志讀寫的操作。
 * 全部為靜態(tài)變量和靜態(tài)方法，對(duì)外提供統(tǒng)一接口。分配對(duì)應(yīng)日志類型的讀寫器，
 * 讀取或?qū)懭敕蠗l件的日志紀(jì)錄。
*/

• 必須寫注釋。geter、seter方法不用寫注釋。寫在類屬性、公有和保護(hù)方法上面。
  示例：

/**
 * 注釋內(nèi)容
 */
private String logType;
/**
 * 注釋內(nèi)容
 */
public void write()

• 成員變量注釋內(nèi)容：成員變量的意義、目的、功能，可能被用到的地方。
• 公有和保護(hù)方法注釋內(nèi)容：列出方法的一句話功能簡(jiǎn)述、功能詳細(xì)描述、輸入?yún)?shù)、輸出參數(shù)、返回值、違例等。
  格式：

/**
 * 〈一句話功能簡(jiǎn)述〉
 * 〈功能詳細(xì)描述〉
 * @param  [參數(shù)1] [in或out]  [參數(shù)1說(shuō)明]
 * @param  [參數(shù)2] [in或out]  [參數(shù)2說(shuō)明]
 * @return [返回類型說(shuō)明]
 * @exception/throws [違例類型] [違例說(shuō)明]
*/

說(shuō)明： @exception或throws 列出可能仍出的異常；。
示例：

/**
 * 用MD5算法計(jì)算輸入字符串的32位摘要
 * @param sIn [in] 待處理的字符串
 * @param sOut [out] sIn的32為摘要，調(diào)用函數(shù)負(fù)責(zé)new sOut對(duì)象
 * @return boolean
 */
public static boolean getMd5(String sIn, StringBuffer sOut) 

• 注釋應(yīng)與其描述的代碼相近，對(duì)代碼的注釋應(yīng)放在其上方或右方（對(duì)單條語(yǔ)句的注釋）相鄰位置，不可放在下面，如放于上方則需與其上面的代碼用空行隔開。
• 注釋與所描述內(nèi)容進(jìn)行同樣的縮排。
  說(shuō)明：可使程序排版整齊，并方便注釋的閱讀與理解。
  示例：如下例子，排版不整齊，閱讀稍感不方便。

public void example( )
{
// 注釋
     CodeBlock One
    
          // 注釋
     CodeBlock Two
}

應(yīng)改為如下布局。

public void example( )
{
     // 注釋
     CodeBlock One
    
     // 注釋 
     CodeBlock Two
}

• 將注釋與其上面的代碼用空行隔開。
  示例：如下例子，顯得代碼過(guò)于緊湊。

//注釋
program code one
//注釋
program code two

應(yīng)如下書寫：

//注釋
program code one
(空一格)   
//注釋
program code two

• 對(duì)變量的定義和分支語(yǔ)句（條件分支、循環(huán)語(yǔ)句等）對(duì)復(fù)雜的分支必須編寫注釋，如果時(shí)間允許，建議對(duì)所有分支語(yǔ)句寫注釋。
  說(shuō)明：這些語(yǔ)句往往是程序?qū)崿F(xiàn)某一特定功能的關(guān)鍵，對(duì)于維護(hù)人員來(lái)說(shuō)，良好的注釋幫助更好的理解程序，有時(shí)甚至優(yōu)于看設(shè)計(jì)文檔。

• 對(duì)于switch語(yǔ)句下的case語(yǔ)句，如果因?yàn)樘厥馇闆r需要處理完一個(gè)case后進(jìn)入下一個(gè)case處理，必須在該case語(yǔ)句處理完、下一個(gè)case語(yǔ)句前加上明確的注釋。
  說(shuō)明：這樣比較清楚程序編寫者的意圖，有效防止無(wú)故遺漏break語(yǔ)句。

• 邊寫代碼邊注釋，修改代碼同時(shí)修改相應(yīng)的注釋，以保證注釋與代碼的一致性。不再有用的注釋要?jiǎng)h除。

• 注釋的內(nèi)容要清楚、明了，含義準(zhǔn)確，防止注釋二義性。
  說(shuō)明：錯(cuò)誤的注釋不但無(wú)益反而有害。

• 避免在注釋中使用縮寫，特別是不常用縮寫。
  說(shuō)明：在使用縮寫時(shí)或之前，應(yīng)對(duì)縮寫進(jìn)行必要的說(shuō)明。

• 用中文寫注釋，禁止用英文寫注釋。

建議

• 避免在一行代碼或表達(dá)式的中間插入注釋。
  說(shuō)明：除非必要，不應(yīng)在代碼或表達(dá)中間插入注釋，否則容易使代碼可理解性變差。

• 通過(guò)對(duì)函數(shù)或過(guò)程、變量、結(jié)構(gòu)等正確的命名以及合理地組織代碼的結(jié)構(gòu)，使代碼成為自注釋的。
  說(shuō)明：清晰準(zhǔn)確的函數(shù)、變量等的命名，可增加代碼可讀性，并減少不必要的注釋。

• 在代碼的功能、意圖層次上進(jìn)行注釋，提供有用、額外的信息。
  說(shuō)明：注釋的目的是解釋代碼的目的、功能和采用的方法，提供代碼以外的信息，幫助讀者理解代碼，防止沒(méi)必要的重復(fù)注釋信息。
  示例：如下注釋意義不大。

// 如果 receiveFlag 為真
if (receiveFlag)

而如下的注釋則給出了額外有用的信息。

// 如果從連結(jié)收到消息 
if (receiveFlag)

• 在程序塊的結(jié)束行右方加注釋標(biāo)記，以表明某程序塊的結(jié)束。
  說(shuō)明：當(dāng)代碼段較長(zhǎng)，特別是多重嵌套時(shí)，這樣做可以使代碼更清晰，更便于閱讀。
  示例：參見如下例子。

if (...)
{
    program code1
    while (index < MAX_INDEX)
    {
        program code2
    } // end of while (index < MAX_INDEX) // 指明該條while語(yǔ)句結(jié)束
} // end of  if (...) // 指明是哪條if語(yǔ)句結(jié)束

• 方法內(nèi)的單行注釋使用 //。
  說(shuō)明：調(diào)試程序的時(shí)候可以方便的使用 /* 。。。*/ 注釋掉一長(zhǎng)段程序。

• 注釋使用中文注釋和中文標(biāo)點(diǎn)，不得用英文寫注釋。方法和類描述的第一句話盡量使用簡(jiǎn)潔明了的話概括一下功能，然后加以句號(hào)。接下來(lái)的部分可以詳細(xì)描述。
  說(shuō)明：JavaDoc工具收集簡(jiǎn)介的時(shí)候使用選取第一句話。

• 順序?qū)崿F(xiàn)流程的說(shuō)明使用1、2、3、4在每個(gè)實(shí)現(xiàn)步驟部分的代碼前面進(jìn)行注釋。
  示例：如下是對(duì)設(shè)置屬性的流程注釋

//1、 判斷輸入?yún)?shù)是否有效。
...
// 2、設(shè)置本地變量。
...

• 一些復(fù)雜的代碼需要說(shuō)明。
  示例：這里主要是對(duì)閏年算法的說(shuō)明。

//1. 如果能被4整除，是閏年；
//2. 如果能被100整除，不是閏年.；
//3. 如果能被400整除，是閏年.。