Java註釋規範（轉載）

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

Java 的語法與 C++ 及爲相似，那麼，你知道 Java 的註釋有幾種嗎？是兩種？ 　　

// 註釋一行　　

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

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

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

 

1. 
   
2. 註釋要簡單明瞭。
   
   

   
   String userName = null; //用戶名

   
   
3. 邊寫代碼邊註釋，修改代碼同時修改相應的註釋，以保證註釋與代碼的一致性。
4. 在必要的地方註釋，註釋量要適中。註釋的內容要清楚、明瞭，含義準確，防
   
   止註釋二義性。保持註釋與其描述的代碼相鄰，即註釋的就近原則。
5. 對代碼的註釋應放在其上方相鄰位置，不可放在下面。對數據結構的註釋應放在
   
   其上方相鄰位置，不可放在下面；對結構中的每個域的註釋應放在此域的右方；
   
   同一結構中不同域的註釋要對齊。
   
6. 變量、常量的註釋應放在其上方相鄰位置或右方。 
   
7. 全局變量要有較詳細的註釋，包括對其功能、取值範圍、哪些函數或過程存取它以
   
   及存取時注意事項等的說明。
   
8. 在每個源文件的頭部要有必要的註釋信息，包括：文件名；版本號；作者；生成日
   
   期；模塊功能描述（如功能、主要算法、內部各部分之間的關係、該文件與其它文
   
   件關係等）；主要函數或過程清單及本文件歷史修改記錄等。
   
   

    

   /**
      * 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
      **/
   
   

    

   
   
9. 在每個函數或過程的前面要有必要的註釋信息，包括：函數或過程名稱；功能描
   
   述；輸入、輸出及返回值說明；調用關係及被調用關係說明等
   
   

    

    /**
         * Description :checkout 提款
         * @param Hashtable cart info
         * @param OrderBean order info
         * @return String
         */
        public String checkout(Hashtable htCart, OrderBean orderBean) throws Exception
        { }
   
   
   

    

10. javadoc註釋標籤語法
    

    
    @author 對類的說明 標明開發該類模塊的作者 
    @version 對類的說明 標明該類模塊的版本 
    @see 對類、屬性、方法的說明 參考轉向，也就是相關主題 
    @param 對方法的說明 對方法中某參數的說明 
    @return 對方法的說明 對方法返回值的說明 
    @exception 對方法的說明 對方法可能拋出的異常進行說明