Java注釋規(guī)范整理    在軟件開發(fā)的過程中總是強調(diào)注釋的規(guī)范，但是沒有一個具體的標準進行說明，通常都是在代碼編寫規(guī)范中簡單的描述幾句，不能作為一個代碼注釋檢查的標準和依據(jù)，做什么都要有一個依據(jù)嗎:),現(xiàn)在我特整理了一個《Java的注釋規(guī)范》，內(nèi)容來自網(wǎng)絡、書籍和自己的實際積累。
JAVA注釋規(guī)范
一、背景
1、當我們第一次接觸某段代碼，但又被要求在極短的時間內(nèi)有效地分析這段代碼，我們需要什么樣的注釋信息？
2、怎么樣避免我們的注釋冗長而且凌亂不堪呢？
3、在多人協(xié)同開發(fā)、維護的今天，我們需要怎么樣的注釋來保證高質(zhì)、高交的進行開發(fā)和維護工作呢？
二、意義
程序中的注釋是程序設計者與程序閱讀者之間通信的重要手段。應用注釋規(guī)范對于軟件本身和軟件開發(fā)人員而言尤為重要。并且在流行的敏捷開發(fā)思想中已經(jīng)提出了將注釋轉(zhuǎn)為代碼的概念。好的注釋規(guī)范可以盡可能的減少一個軟件的維護成本 , 并且?guī)缀鯖]有任何一個軟件，在其整個生命周期中，均由最初的開發(fā)人員來維護。好的注釋規(guī)范可以改善軟件的可讀性，可以讓開發(fā)人員盡快而徹底地理解新的代碼。好的注釋規(guī)范可以最大限度的提高團隊開發(fā)的合作效率。長期的規(guī)范性編碼還可以讓開發(fā)人員養(yǎng)成良好的編碼習慣，甚至鍛煉出更加嚴謹?shù)乃季S能力。
三、注釋的原則
1、 注釋形式統(tǒng)一
在整個應用程序中，使用具有一致的標點和結構的樣式來構造注釋。如果在其他項目組發(fā)現(xiàn)他們的注釋規(guī)范與這份文檔不同，按照他們的規(guī)范寫代碼，不要試圖在既成的規(guī)范系統(tǒng)中引入新的規(guī)范。
2、 注釋的簡潔
內(nèi)容要簡單、明了、含義準確，防止注釋的多義性，錯誤的注釋不但無益反而有害。
3、 注釋的一致性
在寫代碼之前或者邊寫代碼邊寫注釋，因為以后很可能沒有時間來這樣做。另外，如果有機會復查已編寫的代碼，在今天看來很明顯的東西六周以后或許就不明顯了。通常描述性注釋先于代碼創(chuàng)建，解釋性注釋在開發(fā)過程中創(chuàng)建，提示性注釋在代碼完成之后創(chuàng)建。修改代碼的同時修改相應的注釋，以保證代碼與注釋的同步。
4、 注釋的位置
保證注釋與其描述的代碼相鄰，即注釋的就近原則。對代碼的注釋應放在其上方相鄰或右方的位置，不可放在下方。避免在代碼行的末尾添加注釋；行尾注釋使代碼更難閱讀。不過在批注變量聲明時，行尾注釋是合適的；在這種情況下，將所有行尾注釋要對齊。
5、 注釋的數(shù)量
注釋必不可少，但也不應過多，在實際的代碼規(guī)范中，要求注釋占程序代碼的比例達到20%左右。注釋是對代碼的“提示”，而不是文檔，程序中的注釋不可喧賓奪主，注釋太多了會讓人眼花繚亂，注釋的花樣要少。不要被動的為寫注釋而寫注釋。
6、刪除無用注釋
在代碼交付或部署發(fā)布之前，必須刪掉臨時的或無關的注釋，以避免在日后的維護工作中產(chǎn)生混亂。
7、 復雜的注釋
如果需要用注釋來解釋復雜的代碼，請檢查此代碼以確定是否應該重寫它。盡一切可能不注釋難以理解的代碼，而應該重寫它。盡管一般不應該為了使代碼更簡單便于使用而犧牲性能，但必須保持性能和可維護性之間的平衡。
8、 多余的注釋
描述程序功能和程序各組成部分相互關系的高級注釋是最有用的，而逐行解釋程序如何工作的低級注釋則不利于讀、寫和修改，是不必要的，也是難以維護的。避免每行代碼都使用注釋。如果代碼本來就是清楚、一目了然的則不加注釋，避免多余的或不適當?shù)淖⑨尦霈F(xiàn)。
9、必加的注釋
典型算法必須有注釋。在代碼不明晰或不可移植處必須有注釋。在代碼修改處加上修改標識的注釋。在循環(huán)和邏輯分支組成的代碼中添加注釋。為了防止問題反復出現(xiàn)，對錯誤修復和解決方法的代碼使用注釋，尤其是在團隊環(huán)境中。
10、注釋在編譯代碼時會被忽略，不編譯到最后的可執(zhí)行文件中，所以注釋不
會增加可執(zhí)行文件的大小。
四、JAVA注釋技巧
1、空行和空白字符也是一種特殊注釋。利用縮進和空行，使代碼與注釋容易區(qū)
別，并協(xié)調(diào)美觀。
2、當代碼比較長，特別是有多重嵌套時，為了使層次清晰，應當在一些段落的
結束處加注釋（在閉合的右花括號后注釋該閉合所對應的起點），注釋不能
寫得很長，只要能表示是哪個控制語句控制范圍的結束即可，這樣便于閱讀。
3、將注釋與注釋分隔符用一個空格分開，在沒有顏色提示的情況下查看注釋時，
這樣做會使注釋很明顯且容易被找到。
4、不允許給塊注釋的周圍加上外框。這樣看起來可能很漂亮，但是難于維護。
5、每行注釋（連同代碼）不要超過120個字(1024×768)，最好不要超過80
字(800×600) 。
6、Java編輯器（IDE）注釋快捷方式。Ctrl+/ 注釋當前行,再按則取消注釋。
7、對于多行代碼的注釋，盡量不采用“/*......*/”，而采用多行“//”注釋，
這樣雖然麻煩，但是在做屏蔽調(diào)試時不用查找配對的“/*......*/”。
8、注釋作為代碼切換開關，用于臨時測試屏蔽某些代碼。
例一：
//*/
   codeSegement1;
//*/
改動第一行就成了：
/*/
   codeSegement1;
//*/
例二：
//----------------------第一段有效，第二段被注釋
//*/
   codeSegement1;
/*/
   codeSegement2;
//*/
只需刪除第一行的/就可以變成：
//----------------------第一段被注釋，第二段有效
/*/
   codeSegement1;
/*/
   codeSegement2;
//*/
五、JAVA注釋方法及格式
1、單行(single-line)--短注釋：//……   
單獨行注釋：在代碼中單起一行注釋， 注釋前最好有一行空行，并與其后的代碼具有一樣的縮進層級。如果單行無法完成，則應采用塊注釋。
注釋格式：/* 注釋內(nèi)容 */

行頭注釋：在代碼行的開頭進行注釋。主要為了使該行代碼失去意義。
注釋格式：// 注釋內(nèi)容
  
行尾注釋：尾端(trailing)--極短的注釋，在代碼行的行尾進行注釋。一般與代碼行后空8（至少4）個格，所有注釋必須對齊。
注釋格式：代碼 + 8（至少4）個空格 + // 注釋內(nèi)容
2、塊(block)--塊注釋：/*……*/
注釋若干行，通常用于提供文件、方法、數(shù)據(jù)結構等的意義與用途的說明，或者算法的描述。一般位于一個文件或者一個方法的前面，起到引導的作用，也可以根據(jù)需要放在合適的位置。這種域注釋不會出現(xiàn)在HTML報告中。注釋格式通常寫成：
/*
  * 注釋內(nèi)容
  */
3、文檔注釋：/**……*/
注釋若干行，并寫入javadoc文檔。每個文檔注釋都會被置于注釋定界符
/**......*/之中，注釋文檔將用來生成HTML格式的代碼報告，所以注釋文
檔必須書寫在類、域、構造函數(shù)、方法，以及字段(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./javadoc/index.html
4、javadoc注釋標簽語法
@author    對類的說明 標明開發(fā)該類模塊的作者
@version   對類的說明 標明該類模塊的版本
@see      對類、屬性、方法的說明 參考轉(zhuǎn)向，也就是相關主題
@param    對方法的說明 對方法中某參數(shù)的說明
@return    對方法的說明 對方法返回值的說明
@exception  對方法的說明 對方法可能拋出的異常進行說明
六、JAVA注釋具體實現(xiàn)
1、源文件注釋
源文件注釋采用 /** …… */，在每個源文件的頭部要有必要的注釋信息，包括：文件名；文件編號；版本號；作者；創(chuàng)建時間；文件描述包括本文件歷史修改記錄等。中文注釋模版：
/**
* 文 件 名 :
    * CopyRright (c) 2008-xxxx:
* 文件編號：
* 創(chuàng) 建 人：
* 日    期：
* 修 改 人：
* 日   期：
* 描   述：
* 版 本 號：
*/

2、類（模塊）注釋：
類（模塊）注釋采用 /** …… */，在每個類（模塊）的頭部要有必要的注釋信息，包括：工程名；類（模塊）編號；命名空間；類可以運行的JDK版本；版本號；作者；創(chuàng)建時間；類（模塊）功能描述（如功能、主要算法、內(nèi)部各部分之間的關系、該類與其類的關系等，必要時還要有一些如特別的軟硬件要求等說明）；主要函數(shù)或過程清單及本類（模塊）歷史修改記錄等。
英文注釋模版：
/**
* CopyRright (c)2008-xxxx:   <展望軟件Forsoft >                         
    * Project:                     <項目工程名 >                                         
* Module ID:   <(模塊)類編號，可以引用系統(tǒng)設計中的類編號>   
    * Comments:  <對此類的描述，可以引用系統(tǒng)設計中的描述>                                          
* JDK version used:      <JDK1.6>                             
* Namespace:           <命名空間>                             
* Author：        <作者中文名或拼音縮寫>                
* Create Date：  <創(chuàng)建日期，格式:YYYY-MM-DD>
* Modified By：   <修改人中文名或拼音縮寫>                                        
* Modified Date:  <修改日期，格式:YYYY-MM-DD>                                   
    * Why & What is modified  <修改原因描述>   
* Version:                  <版本號>                      
*/
如果模塊只進行部分少量代碼的修改時，則每次修改須添加以下注釋：
//Rewriter
//Rewrite Date：<修改日期:格式YYYY-MM-DD> Start1：
/* 原代碼內(nèi)容*/
//End1：
將原代碼內(nèi)容注釋掉，然后添加新代碼使用以下注釋：
//Added by
//Add date：<添加日期，格式：YYYY-MM-DD> Start2：
//End2：
如果模塊輸入輸出參數(shù)或功能結構有較大修改，則每次修改必須添加以下
注釋：
//Log ID：<Log編號,從1開始一次增加>
//Depiction：<對此修改的描述>
//Writer：修改者中文名
//Rewrite Date：<模塊修改日期，格式：YYYY-MM-DD>

2、接口注釋：
接口注釋采用 /** …… */，在滿足類注釋的基礎之上，接口注釋應該包含描述接口的目的、它應如何被使用以及如何不被使用，塊標記部分必須注明作者和版本。在接口注釋清楚的前提下對應的實現(xiàn)類可以不加注釋。

3、構造函數(shù)注釋：
構造函數(shù)注釋采用 /** …… */，描述部分注明構造函數(shù)的作用，不一定有塊標記部分。
注釋模版一：
/**
* 默認構造函數(shù)
*/
注釋模版二：
/**
* Description :       帶參數(shù)構造函數(shù),
*                       初始化模式名,名稱和數(shù)據(jù)源類型
* @param schema：   模式名
* @param name：   名稱
* @param type： 數(shù)據(jù)源類型
*/

4、函數(shù)注釋：
函數(shù)注釋采用 /** ……*/，在每個函數(shù)或者過程的前面要有必要的注釋信息，包括：函數(shù)或過程名稱；功能描述；輸入、輸出及返回值說明；調(diào)用關系及被調(diào)用關系說明等。函數(shù)注釋里面可以不出現(xiàn)版本號（@version）。
注釋模版一：
/**
  * 函 數(shù) 名 :
  * 功能描述：
* 輸入?yún)?shù):     <按照參數(shù)定義順序>
*             <@param后面空格后跟著參數(shù)的變量名字
*            （不是類型），空格后跟著對該參數(shù)的描述。>
*
* 返 回 值:  - 類型 <說明>
*            <返回為空（void）的構造函數(shù)或者函數(shù)，
*            @return可以省略; 如果返回值就是輸入?yún)?shù)，必須 *            用與輸入?yún)?shù)的@param相同的描述信息; 必要的時*            候注明特殊條件寫的返回值。>
* 異    常：<按照異常名字的字母順序>
* 創(chuàng) 建 人:
* 日    期:
* 修 改 人:
* 日    期:
*/
注釋模版二：
/**
* FunName:           getFirstSpell
  * Description :      獲取漢字拼音首字母的字符串，
*                   被生成百家姓函數(shù)調(diào)用
  * @param：         str the String是包含漢字的字符串
  * @return String：漢字返回拼音首字母字符串；
*                  英文字母返回對應的大寫字母；
*                 其他非簡體漢字返回 '0'；
* @Author:       ghc
* @Create Date: 2008-07-02
*/

5、方法注釋：
方法注釋采用 /** …… */，對于設置 (Set 方法 ) 與獲取 (Get 方法 ) 成員的方法，在成員變量已有說明的情況下，可以不加注釋；普通成員方法要求說明完成什么功能，參數(shù)含義是什么且返回值什么；另外方法的創(chuàng)建時間必須注釋清楚，為將來的維護和閱讀提供寶貴線索。

6、方法內(nèi)部注釋：
控制結構，代碼做了些什么以及為什么這樣做，處理順序等，特別是復雜的邏輯處理部分，要盡可能的給出詳細的注釋。
   
7、 全局變量注釋：
要有較詳細的注釋，包括對其功能、取值范圍、哪些函數(shù)或者過程存取以及存取時注意事項等的說明。

8、局部（中間）變量注釋：
主要變量必須有注釋，無特別意義的情況下可以不加注釋。

9、實參/參數(shù)注釋：
參數(shù)含義、及其它任何約束或前提條件。

10、字段/屬性注釋： 字段描述，屬性說明。

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