java代碼註釋規範

@since 
JDK版本

用於標識編譯該文件所須要的JDK環境。

適用範圍：文件、類

例：     * @since 
JDK1.6

@version 版本號

用於標識註釋對象的版本號

適用範圍：文件、類、方法

例：     * @version 1.0

@see 連接目標

 

 

代碼註釋是架起程序設計者與程序閱讀者之間的通訊橋樑，最大限度的提升團隊開發合做效率。也是程序代碼可維護性的重要環節之一。因此咱們不是爲寫註釋而寫註釋。下面說一下咱們在訴求網二期開發中使用的代碼註釋規範，供你們參考下。

原則：

一、註釋形式統一

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

二、註釋內容準確簡潔

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

 

註釋條件：

一、基本註釋（必須加）

(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 classTest 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 voidaddColor(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.   字段/屬性註釋

例如：

public class 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;//目前不支持定時 因此建立後即刻發送

   privateSet<EmailList> EmailList;

……

}

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