Java的注釋規範整理

轉自：http://gyhgc.javaeye.com/blog/225039

一、背景

1、當我們第一次接觸某段代碼，但又被要求在極短的時間內有效地分析這段代碼，我們需要什麼樣的注釋資訊？

2、怎麼樣避免我們的注釋冗長而且淩亂不堪呢？

3、在多人協同開發、維護的今天，我們需要怎麼樣的注釋來保證高質、高交的進行開發和維護工作呢？

二、意義

程式中的注釋是程式設計者與程式閱讀者之間通訊的重要手段。應用注釋規範對於軟體本身和軟體開發人員而言尤為重要。並且在流行的敏捷開發思想中已
經提出了將注釋轉為代碼的概念。好的注釋規範可以儘可能的減少一個軟體的維護成本 ,
並且幾乎沒有任何一個軟體，在其整個生命週期中，均由最初的開發人員來維護。好的注釋規範可以改善軟體的可讀性，可以讓開發人員儘快而徹底地理解新的代
碼。好的注釋規範可以最大限度的提高團隊開發的合作效率。長期的規範性編碼還可以讓開發人員養成良好的編碼習慣，甚至鍛鍊出更加嚴謹的思維能力。

三、注釋的原則

1、注釋形式統一

在整個應用程式中，使用具有一致的標點和結構的樣式來構造注釋。如果在其他項目組發現他們的注釋規範與這份文檔不同，按照他們的規範寫代碼，不要試圖在既成的規範系統中引入新的規範。

2、注釋的簡潔

內容要簡單、明了、含義準確，防止注釋的多義性，錯誤的注釋不但無益反而有害。

3、注釋的一致性

在寫代碼之前或者邊寫代碼邊寫注釋，因為以後很可能沒有時間來這樣做。另外，如果有機會複查已編寫的代碼，在今天看來很明顯的東西六周以後或許就
不明顯了。通常描述性注釋先於代碼建立，解釋性注釋在開發過程中建立，提示性注釋在程式碼完成之後建立。修改代碼的同時修改相應的注釋，以保證代碼與注釋的
同步。

4、注釋的位置

保證注釋與其描述的代碼相鄰，即注釋的就近原則。對代碼的注釋應放在其上方相鄰或右方的位置，不可放在下方。避免在程式碼的末尾添加註釋；行章節附註釋使代碼更難閱讀。不過在批註變數聲明時，行章節附註釋是合適的；在這種情況下，將所有行章節附註釋要對齊。

5、注釋的數量

注釋必不可少，但也不應過多，在實際的代碼規範中，要求注釋占程式碼的比例達到20%左右。注釋是對代碼的“提示”，而不是文檔，程式中的注釋不可喧賓奪主，注釋太多了會讓人眼花繚亂，注釋的花樣要少。不要被動的為寫注釋而寫注釋。

6、刪除無用注釋

在代碼交付或部署發布之前，必須刪掉臨時的或無關的注釋，以避免在日後的維護工作中產生混亂。

7、複雜的注釋

如果需要用注釋來解釋複雜的代碼，請檢查此代碼以確定是否應該重寫它。盡一切可能不注釋難以理解的代碼，而應該重寫它。儘管一般不應該為了使代碼更簡單便於使用而犧牲效能，但必須保持效能和可維護性之間的平衡。

8、多餘的注釋

描述程式功能和程式各組成部分相互關係的進階注釋是最有用的，而逐行解釋程式如何工作的低級注釋則不利於讀、寫和修改，是不必要的，也是難以維護的。避免每行代碼都使用注釋。如果代碼本來就是清楚、一目瞭然的則不加註釋，避免多餘的或不適當的注釋出現。

9、必加的注釋

典型演算法必須有注釋。在代碼不明晰或不可移植處必須有注釋。在代碼修改處加上修改標識的注釋。在迴圈和邏輯分支組成的代碼中添加註釋。為了防止問題反覆出現，對錯誤修複和解決方案的代碼使用注釋，尤其是在團隊環境中。

10、注釋在編譯代碼時會被忽略，不編譯到最後的可執行檔中，所以注釋不

會增加可執行檔的大小。

四、JAVA注釋技巧

1、空行和空白字元也是一種特殊注釋。利用縮排和空行，使代碼與注釋容易區

別，並協調美觀。

2、當代碼比較長，特別是有多重嵌套時，為了使層次清晰，應當在一些段落的

結束處加註釋（在閉合的右花括弧後注釋該閉合所對應的起點），注釋不能

寫得很長，只要能表示是哪個控制語句控制範圍的結束即可，這樣便於閱讀。

3、將注釋與注釋分隔字元用一個空格分開，在沒有顏色提示的情況下查看注釋時，

這樣做會使注釋很明顯且容易被找到。

4、不允許給塊注釋的周圍加上外框。這樣看起來可能很漂亮，但是難於維護。

5、每行注釋（連同代碼）不要超過120個字(1024×768)，最好不要超過80

字(800×600) 。

6、Java編輯器（IDE）注釋捷徑。Ctrl+/ 注釋當前行,再按則取消注釋。

7、對於多行代碼的注釋，盡量不採用“/*......*/”，而採用多行“//”注釋，

這樣雖然麻煩，但是在做屏蔽調試時不用尋找配對的“/*......*/”。

8、注釋作為代碼切換開關，用於臨時測試屏蔽某些代碼。

例一：

//*/

   codeSegement1;

//*/

改動第一行就成了：

/*/

   codeSegement1;

//*/

例二：

//----------------------第一段有效，第二段被注釋

//*/

   codeSegement1;

/*/

   codeSegement2;

//*/

只需刪除第一行的/就可以變成：

//----------------------第一段被注釋，第二段有效

/*/

   codeSegement1;

/*/

   codeSegement2;

//*/

五、JAVA注釋方法及格式

1、單行(single-line)--短注釋：//……   

單獨行注釋：在代碼中單起一行注釋， 注釋前最好有一行空行，並與其後的代碼具有一樣的縮排層級。如果單行無法完成，則應採用塊注釋。

注釋格式：/* 注釋內容 */

行頭注釋：在程式碼的開頭進行注釋。主要為了使該行代碼失去意義。

注釋格式：// 注釋內容

  

行章節附註釋：尾端(trailing)--極短的注釋，在程式碼的行尾進行注釋。一般與程式碼後空8（至少4）個格，所有注釋必須對齊。

注釋格式：代碼 + 8（至少4）個空格 + // 注釋內容

2、塊(block)--塊注釋：/*……*/

注釋若干行，通常用於提供檔案、方法、資料結構等的意義與用途的說明，或者演算法的描述。一般位於一個檔案或者一個方法的前面，起到引導的作用，也可以根據需要放在合適的位置。這種域注釋不會出現在HTML報告中。注釋格式通常寫成：

/*

  * 注釋內容

  */

3、文檔注釋：/**……*/

注釋若干行，並寫入javadoc文檔。每個文檔注釋都會被置於注釋定界符

/**......*/之中，注釋文檔將用來產生HTML格式的代碼報告，所以注釋文

檔必須書寫在類、域、建構函式、方法，以及欄位(field)定義之前。注釋文檔由兩部分組成——描述、塊標記。注釋文檔的格式如下：

/**

* The doGet method of the servlet.

* This method is called when a form has its tag value method

   * equals to get.

* @param request

*  the request send by the client to the server

* @param response

*  the response send by the server to the client

* @throws ServletException

*  if an error occurred

* @throws IOException

*  if an error occurred

*/

public void doGet (HttpServletRequest request, HttpServletResponse response)

throws ServletException, IOException {

    doPost(request, response);

}

前兩行為描述，描述完畢後，由@符號起頭為塊標記注釋。更多有關文檔注

釋和javadoc的詳細資料，參見javadoc的首頁： http://java.sun.com/javadoc/index.html

4、javadoc注釋標籤文法

@author    對類的說明 標明開發該類別模組的作者

@version   對類的說明 標明該類別模組的版本

@see      對類、屬性、方法的說明 參考轉向，也就是相關主題

@param    對方法的說明 對方法中某參數的說明

@return    對方法的說明 對方法傳回值的說明

@exception  對方法的說明 對方法可能拋出的異常進行說明

六、JAVA注釋具體實現

1、源檔案注釋

源檔案注釋採用 /** …… */，在每個源檔案的頭部要有必要的注釋資訊，包括：檔案名稱；檔案編號；版本號碼；作者；建立時間；檔案描述包括本檔案曆史修改記錄等。中文注釋模版：

/**

* 文 件 名 :

    * CopyRright (c) 2008-xxxx:

* 檔案編號：

* 創 建 人：

* 日    期：

* 修 改 人：

* 日   期：

* 描   述：

* 版 本 號：

*/

2、類（模組）注釋：

類（模組）注釋採用 /** ……
*/，在每個類（模組）的頭部要有必要的注釋資訊，包括：工程名；類（模組）編號；命名空間；類可以啟動並執行JDK版本；版本號碼；作者；建立時間；類（模
塊）功能描述（如功能、主要演算法、內部各部分之間的關係、該類與其類的關係等，必要時還要有一些如特別的軟硬體要求等說明）；主要函數或過程清單及本類
（模組）曆史修改記錄等。

英文注釋模版：

/**

* CopyRright (c)2008-xxxx:   <展望軟體Forsoft >                         

    * Project:                     <項目工程名 >                                         

* Module ID:   <(模組)類編號，可以引用系統設計中的類編號>   

    * Comments:  <對此類的描述，可以引用系統設計中的描述>                                          

* JDK version used:      <JDK1.6>                             

* Namespace:           <命名空間>                             

* Author：        <作者中文名或拼音縮寫>                

* Create Date：  <建立日期，格式:YYYY-MM-DD>

* Modified By：   <修改人中文名或拼音縮寫>                                        

* Modified Date:  <修改日期，格式:YYYY-MM-DD>                                   

    * Why & What is modified  <修改原因描述>   

* Version:                  <版本號碼>                      

*/

如果模組只進行部分少量代碼的修改時，則每次修改須添加以下注釋：

//Rewriter

//Rewrite Date：<修改日期:格式YYYY-MM-DD> Start1：

/* 原代碼內容*/

//End1：

將原代碼內容注釋掉，然後添加新代碼使用以下注釋：

//Added by

//Add date：<添加日期，格式：YYYY-MM-DD> Start2：

//End2：

如果模組輸入輸出參數或功能結構有較大修改，則每次修改必須添加以下

注釋：

//Log ID：<Log編號,從1開始一次增加>

//Depiction：<對此修改的描述>

//Writer：修改者中文名

//Rewrite Date：<模組修改日期，格式：YYYY-MM-DD>

2、介面注釋：

介面注釋採用 /** …… */，在滿足類注釋的基礎之上，介面注釋應該包含描述介面的目的、它應如何被使用以及如何不被使用，塊標記部分必須註明作者和版本。在介面注釋清楚的前提下對應的實作類別可以不加註釋。

3、建構函式注釋：

建構函式注釋採用 /** …… */，描述部分註明建構函式的作用，不一定有塊標記部分。

注釋模版一：

/**

* 預設建構函式

*/

注釋模版二：

/**

* Description :       帶參數建構函式,

*                       初始化模式名,名稱和資料來源類型

* @param schema：   模式名

* @param name：   名稱

* @param type： 資料來源類型

*/

4、函數注釋：

函數注釋採用 /** ……*/，在每個函數或者過程的前面要有必要的注釋資訊，包括：函數或過程名稱；功能描述；輸入、輸出及傳回值說明；調用關係及被調用關係說明等。函數注釋裡面可以不出現版本號碼（@version）。

注釋模版一：

/**

  * 函 數 名 :

  * 功能描述：

* 輸入參數:     <按照參數定義順序>

*             <@param後面空格後跟著參數的變數名字

*            （不是類型），空格後跟著對該參數的描述。>

*

* 返 回 值:  - 類型 <說明>

*            <返回為空白（void）的建構函式或者函數，

*            @return可以省略; 如果傳回值就是輸入參數，必須 *            用與輸入參數的@param相同的描述資訊; 必要的時*            候註明特殊條件寫的傳回值。>

* 異    常：<按照異常名字的字母順序>

* 創 建 人:

* 日    期:

* 修 改 人:

* 日    期:

*/

注釋模版二：

/**

* FunName:           getFirstSpell

  * Description :      擷取漢字拼音首字母的字串，

*                   被產生百家姓函數調用

  * @param：         str the String是包含漢字的字串

  * @return String：漢字返回拼音首字母字串；

*                  英文字母返回對應的大寫字母；

*                 其他非簡體漢字返回 '0'；

* @Author:       ghc

* @Create Date: 2008-07-02

*/

5、方法注釋：

方法注釋採用 /** …… */，對於設定 (Set 方法 ) 與擷取 (Get 方法 )
成員的方法，在成員變數已有說明的情況下，可以不加註釋；普通成員方法要求說明完成什麼功能，參數含義是什麼且傳回值什麼；另外方法的建立時間必須注釋清
楚，為將來的維護和閱讀提供寶貴線索。

6、方法內部注釋：

控制結構，代碼做了些什麼以及為什麼這樣做，處理順序等，特別是複雜的邏輯處理部分，要儘可能的給出詳細的注釋。

   

7、全域變數注釋：

要有較詳細的注釋，包括對其功能、取值範圍、哪些函數或者過程存取以及存取時注意事項等的說明。

8、局部（中間）變數注釋：

主要變數必須有注釋，無特別意義的情況下可以不加註釋。

9、實參/參數注釋：

參數含義、及其它任何約束或前提條件。

10、欄位/屬性注釋： 欄位描述，屬性說明。

11、常量：常量通常具有一定的實際意義，要定義相應說明。