Java註釋規範整理

Version:0.9 StartHTML:-1 EndHTML:-1 StartFragment:00000099 EndFragment:00018736

    在軟件開發的過程當中老是強調註釋的規範，可是沒有一個具體的標準進行說明，一般都是在代碼編寫規範中簡單的描述幾句，不能做爲一個代碼註釋檢查的標準和依據，作什麼都要有一個依據嗎:),如今我特整理了一個《Java的註釋規範》，內容來自網絡、書籍和本身的實際積累。
JAVA註釋規範

版本/狀態 做者 版本日期
1.0 ghc 2008-07-02

1、背景
一、當咱們第一次接觸某段代碼，但又被要求在極短的時間內有效地分析這段代碼，咱們須要什麼樣的註釋信息？
二、怎麼樣避免咱們的註釋冗長並且凌亂不堪呢？
三、在多人協同開發、維護的今天，咱們須要怎麼樣的註釋來保證高質、高交的進行開發和維護工做呢？
2、意義
程序中的註釋是程序設計者與程序閱讀者之間通訊的重要手段。應用註釋規範對於軟件自己和軟件開發人員而言尤其重要。而且在流行的敏捷開發思想中已經提出了將註釋轉爲代碼的概念。好的註釋規範能夠儘量的減小一個軟件的維護成本 , 而且幾乎沒有任何一個軟件，在其整個生命週期中，均由最初的開發人員來維護。好的註釋規範能夠改善軟件的可讀性，可讓開發人員儘快而完全地理解新的代碼。好的註釋規範能夠最大限度的提升團隊開發的合做效率。長期的規範性編碼還可讓開發人員養成良好的編碼習慣，甚至鍛煉出更加嚴謹的思惟能力。
3、註釋的原則
一、 註釋形式統一
在整個應用程序中，使用具備一致的標點和結構的樣式來構造註釋。若是在其餘項目組發現他們的註釋規範與這份文檔不一樣，按照他們的規範寫代碼，不要試圖在既成的規範系統中引入新的規範。
二、 註釋的簡潔
內容要簡單、明瞭、含義準確，防止註釋的多義性，錯誤的註釋不但無益反而有害。
三、 註釋的一致性
在寫代碼以前或者邊寫代碼邊寫註釋，由於之後極可能沒有時間來這樣作。另外，若是有機會複查已編寫的代碼，在今天看來很明顯的東西六週之後或許就不明顯了。一般描述性註釋先於代碼建立，解釋性註釋在開發過程當中建立，提示性註釋在代碼完成以後建立。修改代碼的同時修改相應的註釋，以保證代碼與註釋的同步。
四、 註釋的位置
保證註釋與其描述的代碼相鄰，即註釋的就近原則。對代碼的註釋應放在其上方相鄰或右方的位置，不可放在下方。避免在代碼行的末尾添加註釋；行尾註釋使代碼更難閱讀。不過在批註變量聲明時，行尾註釋是合適的；在這種狀況下，將全部行尾註釋要對齊。
五、 註釋的數量
註釋必不可少，但也不該過多，在實際的代碼規範中，要求註釋佔程序代碼的比例達到20%左右。註釋是對代碼的「提示」，而不是文檔，程序中的註釋不可喧賓奪主，註釋太多了會讓人眼花繚亂，註釋的花樣要少。不要被動的爲寫註釋而寫註釋。
六、刪除無用註釋
在代碼交付或部署發佈以前，必須刪掉臨時的或無關的註釋，以免在往後的維護工做中產生混亂。
七、 複雜的註釋
若是須要用註釋來解釋複雜的代碼，請檢查此代碼以肯定是否應該重寫它。盡一切可能不註釋難以理解的代碼，而應該重寫它。儘管通常不該該爲了使代碼更簡單便於使用而犧牲性能，但必須保持性能和可維護性之間的平衡。
八、 多餘的註釋
描述程序功能和程序各組成部分相互關係的高級註釋是最有用的，而逐行解釋程序如何工做的低級註釋則不利於讀、寫和修改，是沒必要要的，也是難以維護的。避免每行代碼都使用註釋。若是代碼原本就是清楚、一目瞭然的則不加註釋，避免多餘的或不適當的註釋出現。
九、必加的註釋
典型算法必須有註釋。在代碼不明晰或不可移植處必須有註釋。在代碼修改處加上修改標識的註釋。在循環和邏輯分支組成的代碼中添加註釋。爲了防止問題反覆出現，對錯誤修復和解決方法的代碼使用註釋，尤爲是在團隊環境中。
十、註釋在編譯代碼時會被忽略，不編譯到最後的可執行文件中，因此註釋不
會增長可執行文件的大小。
4、JAVA註釋技巧
一、空行和空白字符也是一種特殊註釋。利用縮進和空行，使代碼與註釋容易區
別，並協調美觀。
二、當代碼比較長，特別是有多重嵌套時，爲了使層次清晰，應當在一些段落的
結束處加註釋（在閉合的右花括號後註釋該閉合所對應的起點），註釋不能
寫得很長，只要能表示是哪一個控制語句控制範圍的結束便可，這樣便於閱讀。
三、將註釋與註釋分隔符用一個空格分開，在沒有顏色提示的狀況下查看註釋時，
這樣作會使註釋很明顯且容易被找到。
四、不容許給塊註釋的周圍加上外框。這樣看起來可能很漂亮，可是難於維護。
五、每行註釋（連同代碼）不要超過120個字(1024×768)，最好不要超過80
字(800×600) 。
六、Java編輯器（IDE）註釋快捷方式。Ctrl+/ 註釋當前行,再按則取消註釋。
七、對於多行代碼的註釋，儘可能不採用「/*......*/」，而採用多行「//」註釋，
這樣雖然麻煩，可是在作屏蔽調試時不用查找配對的「/*......*/」。
八、註釋做爲代碼切換開關，用於臨時測試屏蔽某些代碼。
例一：
//*/
   codeSegement1;
//*/
改動第一行就成了：
/*/
   codeSegement1;
//*/
例二：
//----------------------第一段有效，第二段被註釋
//*/
   codeSegement1;
/*/
   codeSegement2;
//*/
只需刪除第一行的/就能夠變成：
//----------------------第一段被註釋，第二段有效
/*/
   codeSegement1;
/*/
   codeSegement2;
//*/
5、JAVA註釋方法及格式
一、單行(single-line)--短註釋：//……   
單獨行註釋：在代碼中單起一行註釋， 註釋前最好有一行空行，並與其後的代碼具備同樣的縮進層級。若是單行沒法完成，則應採用塊註釋。
註釋格式：/* 註釋內容 */

行頭註釋：在代碼行的開頭進行註釋。主要爲了使該行代碼失去意義。
註釋格式：// 註釋內容
  
行尾註釋：尾端(trailing)--極短的註釋，在代碼行的行尾進行註釋。通常與代碼行後空8（至少4）個格，全部註釋必須對齊。
註釋格式：代碼 + 8（至少4）個空格 + // 註釋內容
二、塊(block)--塊註釋：/*……*/
註釋若干行，一般用於提供文件、方法、數據結構等的意義與用途的說明，或者算法的描述。通常位於一個文件或者一個方法的前面，起到引導的做用，也能夠根據須要放在合適的位置。這種域註釋不會出如今HTML報告中。註釋格式一般寫成：
/*
  * 註釋內容
  */
三、文檔註釋：/**……*/
註釋若干行，並寫入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
四、javadoc註釋標籤語法
@author    對類的說明 標明開發該類模塊的做者
@version   對類的說明 標明該類模塊的版本
@see      對類、屬性、方法的說明 參考轉向，也就是相關主題
@param    對方法的說明 對方法中某參數的說明
@return    對方法的說明 對方法返回值的說明
@exception  對方法的說明 對方法可能拋出的異常進行說明
6、JAVA註釋具體實現
一、源文件註釋
源文件註釋採用 /** …… */，在每一個源文件的頭部要有必要的註釋信息，包括：文件名；文件編號；版本號；做者；建立時間；文件描述包括本文件歷史修改記錄等。中文註釋模版：
/**
* 文 件 名 :
    * CopyRright (c) 2008-xxxx:
* 文件編號：
* 創 建 人：
* 日    期：
* 修 改 人：
* 日   期：
* 描   述：
* 版 本 號：
*/

二、類（模塊）註釋：
類（模塊）註釋採用 /** …… */，在每一個類（模塊）的頭部要有必要的註釋信息，包括：工程名；類（模塊）編號；命名空間；類能夠運行的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>

二、接口註釋：
接口註釋採用 /** …… */，在知足類註釋的基礎之上，接口註釋應該包含描述接口的目的、它應如何被使用以及如何不被使用，塊標記部分必須註明做者和版本。在接口註釋清楚的前提下對應的實現類能夠不加註釋。

三、構造函數註釋：
構造函數註釋採用 /** …… */，描述部分註明構造函數的做用，不必定有塊標記部分。
註釋模版一：
/**
* 默認構造函數
*/
註釋模版二：
/**
* Description :       帶參數構造函數,
*                       初始化模式名,名稱和數據源類型
* @param schema：   模式名
* @param name：   名稱
* @param type： 數據源類型
*/

四、函數註釋：
函數註釋採用 /** ……*/，在每一個函數或者過程的前面要有必要的註釋信息，包括：函數或過程名稱；功能描述；輸入、輸出及返回值說明；調用關係及被調用關係說明等。函數註釋裏面能夠不出現版本號（@version）。
註釋模版一：
/**
  * 函 數 名 :
  * 功能描述：
* 輸入參數:     <按照參數定義順序>
*             <@param後面空格後跟着參數的變量名字
*            （不是類型），空格後跟着對該參數的描述。>
*
* 返 回 值:  - 類型 <說明>
*            <返回爲空（void）的構造函數或者函數，
*            @return能夠省略; 若是返回值就是輸入參數，必須 *            用與輸入參數的@param相同的描述信息; 必要的時*            候註明特殊條件寫的返回值。>
* 異    常：<按照異常名字的字母順序>
* 創 建 人:
* 日    期:
* 修 改 人:
* 日    期:
*/
註釋模版二：
/**
* FunName:           getFirstSpell
  * Description :      獲取漢字拼音首字母的字符串，
*                   被生成百家姓函數調用
  * @param：         str the String是包含漢字的字符串
  * @return String：漢字返回拼音首字母字符串；
*                  英文字母返回對應的大寫字母；
*                 其餘非簡體漢字返回 '0'；
* @Author:       ghc
* @Create Date: 2008-07-02
*/

五、方法註釋：
方法註釋採用 /** …… */，對於設置 (Set 方法 ) 與獲取 (Get 方法 ) 成員的方法，在成員變量已有說明的狀況下，能夠不加註釋；普通成員方法要求說明完成什麼功能，參數含義是什麼且返回值什麼；另外方法的建立時間必須註釋清楚，爲未來的維護和閱讀提供寶貴線索。

六、方法內部註釋：
控制結構，代碼作了些什麼以及爲何這樣作，處理順序等，特別是複雜的邏輯處理部分，要儘量的給出詳細的註釋。
   
七、 全局變量註釋：
要有較詳細的註釋，包括對其功能、取值範圍、哪些函數或者過程存取以及存取時注意事項等的說明。

八、局部（中間）變量註釋：
主要變量必須有註釋，無特別意義的狀況下能夠不加註釋。

九、實參/參數註釋：
參數含義、及其它任何約束或前提條件。

十、字段/屬性註釋： 字段描述，屬性說明。

十一、常量：常量一般具備必定的實際意義，要定義相應說明。