Java注釋規範

定義這個規範的目的是讓項目中所有的文檔都看起來像一個人寫的，增加可讀性，減少項目組中因為換人而帶來的損失。（這些規範並不是一定要絕對遵守，但是一定要讓程式有良好的可讀性）。

Java 的文法與 C++ 及為相似，那麼，你知道 Java 的注釋有幾種嗎？是兩種？ 　　

// 注釋一行　　

/* ...... */ 注釋若干行

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

/** ...... */ 注釋若干行，並寫入 javadoc 文檔

1. 注釋要簡單明了。
   String userName = null; //使用者名稱
2. 邊寫代碼邊注釋，修改代碼同時修改相應的注釋，以保證注釋與代碼的一致性。
3. 在必要的地方注釋，注釋量要適中。注釋的內容要清楚、明了，含義準確，防

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

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

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

   同一結構中不同域的注釋要對齊。

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

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

7. 在每個源檔案的頭部要有必要的注釋資訊，包括：檔案名稱；版本號碼；作者；產生日

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

   件關係等）；主要函數或過程清單及本檔案曆史修改記錄等。Java代碼 {
   dp.sh.Toolbar.CopyToClipboard(this);return false;
   }" href="http://jiajunde.javaeye.com/blog/359968#">

   1. /**  
   2.    * Copy Right Information   : Neusoft IIT  
   3.    * Project                        : eTrain  
   4.    * JDK version used           : jdk1.3.1  
   5.    * Comments                  : config path  
   6.    * Version                       : 1.01  
   7.    * Modification history     :2003.5.1  
   8.    * Sr Date   Modified By   Why & What is modified  
   9.    * 1. 2003.5.2 Kevin Gao     new  
   10.    **/  

   /**   * 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.  在每個函數或過程的前面要有必要的注釋資訊，包括：函數或過程名稱；功能描

   述；輸入、輸出及傳回值說明；調用關係及被調用關係說明等

   Java代碼 {
   dp.sh.Toolbar.CopyToClipboard(this);return false;
   }" href="http://jiajunde.javaeye.com/blog/359968#">
   1. /**  
   2.      * Description :checkout 提款  
   3.      * @param Hashtable cart info  
   4.      * @param OrderBean order info  
   5.      * @return String  
   6.      */  
   7.     public String checkout(Hashtable htCart, OrderBean orderBean) throws Exception   
   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 對方法的說明 對方法中某參數的說明
   @return 對方法的說明 對方法傳回值的說明