一、背景 
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、常量：常量通常具有一定的實際意義，要定義相應說明。

java 註釋有三種

1、// 註釋一行　　

2、/* ...... */ 註釋若干行

不完全對，除了以上兩種之外，還有第三種，文件註釋： 　　

3、/** ...... */ 註釋若干行，並寫入 javadoc 文件 第三種形式主要是為了生成javadoc檔案,生成api用的.

----------------------------------------------------------------------------------------------------------------------------------------------

1. 註釋要簡單明瞭。

   //使用者名稱

   String userName = null;

2. 邊寫程式碼邊註釋，修改程式碼同時修改相應的註釋，以保證註釋與程式碼的一致性。
3. 在必要的地方註釋，註釋量要適中。註釋的內容要清楚、明瞭，含義準確，防

   止註釋二義性。保持註釋與其描述的程式碼相鄰，即註釋的就近原則。

4. 對程式碼的註釋應放在其上方相鄰位置，不可放在下面。對資料結構的註釋應放在

   其上方相鄰位置，不可放在下面；對結構中的每個域的註釋應放在此域的右方；

   同一結構中不同域的註釋要對齊。(我沒用寫過域定義)

5. 變數、常量的註釋應放在其上方相鄰位置或右方。
6. 全域性變數要有較詳細的註釋，包括對其功能、取值範圍、哪些函式或過程存取它以

   及存取時注意事項等的說明。

7. 在每個原始檔的頭部要有必要的註釋資訊，包括：檔名；版本號；作者；生成日

   期；模組功能描述（如功能、主要演算法、內部各部分之間的關係、該檔案與其它文

   件關係等）；主要函式或過程清單及本檔案歷史修改記錄等。

   /**

       * Copy Right Information    : Neusoft IIT

       * Project                         : eTrain

       * JDK version used            : jdk1.3.1

       * Comments                   : config path

       * Version                        : 1.01

       * Modification history      :2003.5.1

       * Sr Date    Modified By    Why & What is modified

       * 1. 2003.5.2 Kevin Gao      new

       **/

8. 在每個函式或過程的前面要有必要的註釋資訊，包括：函式或過程名稱；功能描

   述；輸入、輸出及返回值說明；呼叫關係及被呼叫關係說明等

   /**

          * Description :checkout 提款

          * @param Hashtable cart info

          * @param OrderBean order info

          * @return String

          */

         public String checkout(Hashtable htCart, OrderBean orderBean) throws Exception

         { }

9. javadoc註釋標籤語法

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

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

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

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

   @type 對引數型別的說明

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

   @exception 對方法的說明 對方法可能丟擲的異常進行說明

   @other：其它說明

-----------------------------------------------------------------------------------------------

各公司都有不同要求，一般方法註釋需要註明該方法的作用，引數說明和返回值。有異常的要加異常說明。有時還要加上建立人，修改人和修改時間。一般這種註釋有 author parementer return Exception等

我在專案中用到了四種註釋(一個空格和Tab都不能多加，保證風格統一！)

1、包註釋

/****************************************************************************
*
* System Name   :ACME_BANK_SYSTEM
* SubSystem Name:director
* ------- ------- ------- -------------- ------- ------- -------
*
* ClassNames：MG043E01SAction
* 利率設定Action，用於控制資料的走向。
*
* $Author Chu Yanwu $
* $Date 2008/11/28 $
* $RCSfile MG043E01SAction.java $
* $Revision 1.1 $
* (c) Copyright IBM JT10, Ltd. 2008.All rights reserved.
*
*
* Ver.    Revision   No.:JAVATEAM10 
* 
* Create Date/Changes History
* ------- ---------- ------------- ------------- ----------------- -----------------------------
* 1.0.0   1.1        -             2008/11/28     Chu Yanwu       Creat MG043E01SAction.java
*
***************************************************************************/

2、類註釋

/**
* <pre>
* ClassNames：AccountNumberClass
* 用作自動生成賬號，通過使用者傳入的引數
* </pre>
* 
* <UL>
* <LI>AccountNumberClass.java</LI>
* <LI>用作生成AccountNumberClass物件</LI>
* <LI>函式AccountNumberOccur(),過載1：以String型別為傳入引數</LI>
* <LI>函式AccountNumberOccur(),過載2：以int型別為傳入引數</LI>
* <LI>Page </LI>
* <LI>Author Chu Yanwu </LI>
* <LI>Version 1.0.0</LI>
* </UL>
* <DL>
* <DT><b></b></DT>
* <DD><BR>
* </DD>
* <BR>
* </DL>
*/

3、方法註釋

/**
* <pre>
* create the Number of Account
* </pre>
* 
* @param type
* @type String
* @param accountType
* @type String
* @param workNo
* @type String
* @return accountNumber
* @type String
* @throws
* 
* @other： 引數 String type 區段1：標示賬戶型別，0企業，1個人； 引數 String accountType
*         區段2：標示賬戶業務範圍及賬戶型別 引數 String workNo 區段3：標示職工號
*/

4、建構函式的註釋

/**
* create the Object of Logger
* 
* @param
* @type
* @return logger
* @type Logger
* @throws
*/

5、欄位變數的註釋（行註釋）

// 1. Populate this dto
// 將form中的值賦值到model（dto)