Java程式碼註釋規範

shuaishuai3409發表於2016-03-02
Java

程式碼註釋是架起程式設計者與程式閱讀者之間的通訊橋樑，最大限度的提高團隊開發合作效率。也是程式程式碼可維護性的重要環節之一。所以我們不是為寫註釋而寫註釋。下面說一下我們在訴求網二期開發中使用的程式碼註釋規範，供大家參考下。

原則：
1、註釋形式統一

在整個應用程式中，使用具有一致的標點和結構的樣式來構造註釋。如果在其它專案中發現它們的註釋規範與這份文件不同，按照這份規範寫程式碼，不要試圖在既成的規範系統中引入新的規範。

2、註釋內容準確簡潔

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

註釋條件：

1、基本註釋（必須加）

(a) 類（介面）的註釋

(b) 建構函式的註釋

(c) 方法的註釋

(d) 全域性變數的註釋

(e) 欄位/屬性的註釋

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

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

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

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

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

(d) 在迴圈和邏輯分支組成的程式碼中加註釋。

(e) 為他人提供的介面必須加詳細註釋。

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

註釋格式：

1、單行(single-line)註釋：“//……”

2、塊(block)註釋：“/……/”

3、文件註釋：“/*……/”

4、javadoc 註釋標籤語法

@author 對類的說明 標明開發該類模組的作者

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

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

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

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

@exception 對方法的說明 對方法可能丟擲的異常進行說明

參考舉例：

  1. 類（介面）註釋

例如：

/**

  • 類的描述

  • @author Administrator

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

*

*/

public classTest extends Button {

……

}

  1. 構造方法註釋

例如:

public class Test extends Button {

/**

  • 構造方法 的描述

  • @param name

  • 按鈕的上顯示的文字

    */

    public Test(String name){

    ……

    }

}

  1. 方法註釋

例如

public class Test extends Button {

/**

  • 為按鈕新增顏色

    *@param color

     按鈕的顏色

*@return

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

  • @author Administrator

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

    */

    public voidaddColor(String color){

    ……

    }

}

  1. 全域性變數註釋

例如：

public final class String

implements java.io.Serializable, Comparable,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

……

}

  1. 欄位/屬性註釋

例如：

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;

……

}

其實規範是自己訂的，只要團隊中大家都統一遵守，統一規範，就會取得好的效果，希望對平時不加註釋的朋友有點幫助。

相關文章