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 對方法的說明 對方法可能丟擲的異常進行說明
參考舉例:
- 類(介面)註釋
例如:
/**
類的描述
@author Administrator
@Time 2012-11-2014:49:01
*
*/
public classTest extends Button {
……
}
- 構造方法註釋
例如:
public class Test extends Button {
/**
構造方法 的描述
@param name
按鈕的上顯示的文字
*/
public Test(String name){
……
}
}
- 方法註釋
例如
public class Test extends Button {
/**
為按鈕新增顏色
*@param color
按鈕的顏色
*@return
*@exception (方法有異常的話加)
@author Administrator
@Time2012-11-20 15:02:29
*/
public voidaddColor(String color){
……
}
}
- 全域性變數註釋
例如:
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
……
}
- 欄位/屬性註釋
例如:
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;
……
}
其實規範是自己訂的,只要團隊中大家都統一遵守,統一規範,就會取得好的效果,希望對平時不加註釋的朋友有點幫助。
相關文章
- HTML 程式碼註釋規範HTML
- PHP程式碼常用註釋規範(PHP Doc)PHP
- java快捷鍵和註釋規範Java
- golang 註釋規範Golang
- CSS 註釋規範CSS
- JavaScript 註釋規範JavaScript
- 批量修改行尾註釋(程式碼規範檢查中)
- Java 程式碼規範if巢狀Java巢狀
- 正規表示式刪除Java程式碼中的註釋Java
- 程式碼書寫規範(Java) (轉)Java
- Java 程式編碼的規範(轉)Java
- PHP 規範 - Symfony 程式碼規範PHP
- Android 程式碼規範 - 命名規範Android
- Android程式碼規範:命名規範Android
- 程式碼規範之前端編寫碼規範前端
- java程式碼規範有什麼意義Java
- 程式碼分支規範
- 程式碼規範整理
- JS程式碼規範JS
- 前端程式碼規範前端
- iOS程式碼規範iOS
- Less程式碼規範
- css程式碼規範CSS
- iOS 程式碼規範iOS
- 程式碼部署規範
- 阿里Java編碼規範阿里Java
- Java 編碼規範 (轉)Java
- java編碼規範 (轉)Java
- java程式設計規範Java程式設計
- 匹配css程式碼註釋的正規表示式CSS
- RFC1867(請求註釋)規範 (轉)
- [吐槽貼,後刪]程式碼命名、註釋還是請稍微規範一丟丟吧
- [轉]高質量JAVA程式碼編寫規範Java
- java中程式碼的註釋和快捷鍵Java
- 程式碼規範淺談
- CSS 程式碼格式規範CSS
- Git程式碼提交規範Git
- 程式碼書寫規範