Java代碼註釋規範一

原則：

一、註釋形式統一

在整個應用程序中，使用具備一致的標點和結構的樣式來構造註釋。若是在其它項目中發現它們的註釋規範與這份文檔不一樣，按照這份規範寫代碼，不要試圖在既成的規範系統中引入新的規範。

二、註釋內容準確簡潔

內容要簡單、明瞭、含義準確，防止註釋的多義性，錯誤的註釋不但無益反而有害。

註釋條件：

一、基本註釋（必須加）

(a)    類（接口）的註釋

(b)    構造函數的註釋

(c)     方法的註釋

(d)    全局變量的註釋

(e)    字段/屬性的註釋

 備註：簡單的代碼作簡單註釋，註釋內容不大於10個字便可，另外，持久化對象或VO對象的getter、setter方法不需加註釋。具體的註釋格式請參考下面舉例。

二、特殊必加註釋（必須加）

(a)    典型算法必須有註釋。

(b)    在代碼不明晰處必須有註釋。

(c)     在代碼修改處加上修改標識的註釋。

(d)    在循環和邏輯分支組成的代碼中加註釋。

(e)    爲他人提供的接口必須加詳細註釋。

 備註：此類註釋格式暫無舉例。具體的註釋格式自行定義，要求註釋內容準確簡潔。

註釋格式：

一、單行(single-line)註釋：「//……」

二、塊(block)註釋：「/*……*/」

三、文檔註釋：「/**……*/」

四、javadoc註釋標籤語法

@author   對類的說明 標明開發該類模塊的做者

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

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

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

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

@exception  對方法的說明 對方法可能拋出的異常進行說明

參考舉例：

1.  類（接口）註釋

例如：

/**

* 類的描述

* @author Administrator

* @Time 2012-11-2014:49:01

*

*/

public class Test extends Button {

  ……

}

2.  構造方法註釋

例如:

public class Test extends Button {

  /**

   * 構造方法的描述

   * @param name

   *       按鈕的上顯示的文字

   */

  public Test(String name){

     ……

  }

}

3.  方法註釋

例如

public class Test extends Button {

  /**

   * 爲按鈕添加顏色

   *@param color

         按鈕的顏色

*@return

*@exception  (方法有異常的話加)

* @author Administrator

* @Time2012-11-20 15:02:29

   */

  public void addColor(String color){

     ……

  }

}

4.  全局變量註釋

例如：

public final class String

   implements java.io.Serializable, Comparable<String>,CharSequence

{

   /** The value is used for characterstorage. */

   private final char value[];

   /** The offset is the first index of thestorage that is used. */

   private final int offset;

   /** The count is the number of charactersin the String. */

   private final int count;

   /** Cache the hash code for the string */

private int hash;// Default to 0

……

}

5.  字段/屬性註釋

例如：

publicclass EmailBody implements Serializable{

   private String id;

   private String senderName;//發送人姓名

   private String title;//不能超過120箇中文字符

   private String content;//郵件正文

   private String attach;//附件，若是有的話

   private String totalCount;//總髮送人數

   private String successCount;//成功發送的人數

   private Integer isDelete;//0不刪除 1刪除

   private Date createTime;//目前不支持定時因此建立後即刻發送

   private Set<EmailList> EmailList;

……

}

其實規範是本身訂的，只要團隊中你們都統一遵照，統一規範，就會取得好的效果，但願對平時不加註釋的朋友有點幫助。