java開發規範總結_代碼注釋規範

標籤：

規範需要平時編碼過程中注意，是一個慢慢養成的好習慣

1.基本規則

   1.注釋應該使代碼更加清晰易懂
   2.注釋要簡單明了，只要提供能夠明確理解程式所必要的資訊就可以了。如果注釋太複雜說明程式需要修改調整，使設計更加合理。
   3.注釋不僅描述程式做了什麼， 還要描述為什麼要這樣做,以及約束
   4.對於一般的getter、setter方法不用注釋
   5.注釋不能嵌套
   6.產生開發文檔的需要用中文編寫

2.三種注釋方式說明

   1.文檔注釋 /** */

      可以對用多行，一般用來對類、介面、成員方法、成員變數、靜態欄位、靜態方法、常量進行說明。Javadoc可以用它來產生代碼的文檔。為了可讀性，可以有縮排和格式控制。
      文檔注釋常採用一些標籤進行文檔的特定用途描述,用於協助Javadoc產生文檔,常用的有：

標籤	Used for	目的
@author name	類/介面	描述代碼的作者，每個作者對應一個這樣的標籤
@deprecated	類 成員方法	說明該段API已經被廢除
@exception name description   或   @throws name description	成員方法	描述方法拋出的異常 每個異常一個對應一個這樣的標籤
@param name description	成員方法	描述成員方法中的參數用途和意義，一個參數對應一個這樣的標籤
@return description	成員方法	描述成員方法的傳回值的意義
@since	類/介面 成員方法	描述該段API開始的時間
@see ClassName	類/介面 成員方法 成員變數	用於引用特定的類描述，一般ClassName用包括包名的全名
@see ClassName#memberfunction	類/介面 成員方法 成員變數	用於引用特定的類的成員方法的描述，一般ClassName用包括包名的全名
@version text	類/介面	版本
@inheritDoc	類/介面 成員方法	繼承的文檔

   

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

   

 

 

 

   2.行注釋 //

      一次只能注釋一行，一般用來簡短的描述某一個局部變數，程式塊的作用

   3.塊注釋： /* */

      在代碼中禁止使用

   4.類/介面注釋

       類/介面描述，一般比較詳細。按照常用的說明順序排列，主要包括
          1.類的主要說明，以。或.結束
          2.類設計的目標，完成什麼樣的功能
          3.<Strong>主要的類使用</Strong>如何使用該類, 包括環境要求,如是否安全執行緒,並發性要求, 以及使用約束
          4.<Strong>已知的BUG</Strong>
          5.描述類的修改曆史:<Strong>修改人+日期＋簡單說明</Strong>
          [email protected]作者、@version版本, @see參照,@since開始版本等資訊如：

/** * This class provides default implementations for the JFC <code>Action</code>  * interface. Standard behaviors like the get and set methods for * <code>Action</code> object properties (icon, text, and enabled) are defined * here. The developer need only subclass this abstract class and * define the <code>actionPerformed</code> method.  * <p> * <strong>Warning:</strong> * Serialized objects of this class will not be compatible with  * future Swing releases.  The current serialization support is appropriate * for short term storage or RMI between applications running the same * version of Swing.  A future release of Swing will provide support for * long term persistence. * * @version 1.41 2015/05/26 * @author xxxxx * @see Action */

      為了使形成的文檔可讀性好，注釋中經常帶有縮排和格式控制。類描述放在類的類定義的緊前面，不能有任何的空行。

3.變數注釋

     1.成員變數、類靜態變數採用文檔注釋，對成員變數的注釋通常包括：
        1)變數的意義
        2)變數的合法範圍
        3)對並發訪問的限制
         如:

 /*** Web.xml檔案中configServlet參數的UIAPP.xml initparam */    public final static String APP_CONFIG = "aaa.uiapp";

    2.局部變數，如演算法相關的變數採用塊或行注釋

public void  func() {    int i; //用於迴圈計數    …………}

   3.參數變數注釋一般用文檔注釋,並且用@param來說明為參數,一般包括

       1） 參數的用途

       2） 對參數值範圍的要求

4.方法注釋

   描述函數的功能，對成員方法，靜態方法一般採用文檔描述，特別是公開的方法。注釋可以很詳細，為了可讀性強也可包含格式控制，如下面說明含有縮排：

/*** Here is a method comment with some very special* formatting that I want indent(1) to ignore.**/

    方法注釋一般包括:
        1.方法的主要說明，以。或.結束
        2.描述方法完成什麼樣的功能,方法的目標,用該方法的原因
        3.描述方法的使用方法,包括使用的環境要求,如前置條件,後置條件和並發性要求
        4.描述已知的bug
        5.描述方法的修改曆史：<Strong>修改人+日期＋簡單說明</Strong> (<修改人+日期＋簡單說明>)
        [email protected] c elements to be inserted into this list.（參數說明）
        [email protected] <tt>true</tt> if this list changed as a result of the call.(傳回值說明)
        [email protected] NullPointerException if the specified Collection is null.（異常說明）
        [email protected]如果重載方法必須參考父類的方法
       10Eclips下採用Alt+Shift+J產生Javadoc說明方法的放回值((@return)

5.修改記錄

    1.在修改一個類前，必須先從SVN中update，之後再進行修改；
    2.修改的地方必須加入注釋，說明修改人，修改原因，修改內容，修改時間；

 

java開發規範總結_代碼注釋規範