資訊專欄INFORMATION COLUMN
摘要：下面說一下我們在訴求網(wǎng)二期開發(fā)中使用的代碼注釋規(guī)范，供大家參考下。在代碼不明晰處必須有注釋。在代碼修改處加上修改標(biāo)識的注釋。在循環(huán)和邏輯分支組成的代碼中加注釋。
代碼注釋是架起程序設(shè)計者與程序閱讀者之間的通信橋梁，最大限度的提高團(tuán)隊開發(fā)合作效率。也是程序代碼可維護(hù)性的重要環(huán)節(jié)之一。所以我們不是為寫注釋而寫注釋。下面說一下我們在訴求網(wǎng)二期開發(fā)中使用的代碼注釋規(guī)范，供大家參考下。
原則：
1、注釋形式統(tǒng)一
在整個應(yīng)用程序中，使用具有一致的標(biāo)點和結(jié)構(gòu)的樣式來構(gòu)造注釋。如果在其它項目中發(fā)現(xiàn)它們的注釋規(guī)范與這份文檔不同，按照這份規(guī)范寫代碼，不要試圖在既成的規(guī)范系統(tǒng)中引入新的規(guī)范。
2、注釋內(nèi)容準(zhǔn)確簡潔
內(nèi)容要簡單、明了、含義準(zhǔn)確，防止注釋的多義性，錯誤的注釋不但無益反而有害。
注釋條件：
1、基本注釋（必須加）
(a) 類（接口）的注釋
(b) 構(gòu)造函數(shù)的注釋
(c) 方法的注釋
(d) 全局變量的注釋
(e) 字段/屬性的注釋
備注：簡單的代碼做簡單注釋，注釋內(nèi)容不大于10個字即可，另外，持久化對象或VO對象的getter、setter方法不需加注釋。具體的注釋格式請參考下面舉例。
2、特殊必加注釋（必須加）
(a) 典型算法必須有注釋。
(b) 在代碼不明晰處必須有注釋。
(c) 在代碼修改處加上修改標(biāo)識的注釋。
(d) 在循環(huán)和邏輯分支組成的代碼中加注釋。
(e) 為他人提供的接口必須加詳細(xì)注釋。
備注：此類注釋格式暫無舉例。具體的注釋格式自行定義，要求注釋內(nèi)容準(zhǔn)確簡潔。
注釋格式：
1、單行(single-line)注釋：“//……”
2、塊(block)注釋：“/……/”
3、文檔注釋：“/*……/”
4、javadoc 注釋標(biāo)簽語法
@author 對類的說明 標(biāo)明開發(fā)該類模塊的作者 @version 對類的說明 標(biāo)明該類模塊的版本 @see 對類、屬性、方法的說明 參考轉(zhuǎn)向，也就是相關(guān)主題 @param 對方法的說明 對方法中某參數(shù)的說明 @return 對方法的說明 對方法返回值的說明 @exception 對方法的說明 對方法可能拋出的異常進(jìn)行說明
參考舉例：
類（接口）注釋
例如：
/**
* 類的描述
* @author Administrator
* @Time 2012-11-2014:49:01
*
*/
public classTest extends Button {
……
}
構(gòu)造方法注釋
例如:
public class Test extends Button {
/**
* 構(gòu)造方法 的描述
* @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;//發(fā)送人姓名
private String title;//不能超過120個中文字符
private String content;//郵件正文
private String attach;//附件，如果有的話
private String totalCount;//總發(fā)送人數(shù)
private String successCount;//成功發(fā)送的人數(shù)
private Integer isDelete;//0不刪除 1刪除
private Date createTime;//目前不支持定時 所以創(chuàng)建后即刻發(fā)送
privateSet EmailList;
……
}
文章版權(quán)歸作者所有，未經(jīng)允許請勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請注明本文地址：http://systransis.cn/yun/67890.html
摘要：今日份重點命名規(guī)范注釋關(guān)鍵字關(guān)鍵字總結(jié)命名規(guī)范規(guī)范的包名名字管理是所有編程語言都必須重視的一個問題。比如說百度，其域名為，那么其對應(yīng)的應(yīng)用的包名前綴就應(yīng)該為。是誰這么大牌總結(jié)本文主要介紹了中的命名規(guī)范注解關(guān)鍵字關(guān)鍵字等內(nèi)容。 歡迎關(guān)注我的微信公眾號，共同打牢Java的基礎(chǔ)，向著遠(yuǎn)方進(jìn)擊 showImg(https://segmentfault.com/img/bVboaBO?w=129...
摘要：大家好，我是樂字節(jié)的小樂，這次要給大家?guī)淼氖亲兞颗c數(shù)據(jù)類型。本文是第一集編程規(guī)范，關(guān)鍵字與標(biāo)識符。后面我們要寫一個程序的過程。需求分析實現(xiàn)代碼體現(xiàn)注釋的作用解釋說明程序，提高了代碼的閱讀性?？梢詭椭覀冋{(diào)試程序。 大家好，我是樂字節(jié)的小樂，這次要給大家?guī)淼氖荍ava變量與數(shù)據(jù)類型。本文是第一集：Java編程規(guī)范，關(guān)鍵字與標(biāo)識符。showImg(https://segmentfaul...
摘要：努力避免硬編碼。一個類的總體行數(shù)盡量控制在行左右不超過一千行。函數(shù)注釋函數(shù)注釋采用，在每個函數(shù)或者過程的前面要有必要的注釋信息，包括函數(shù)或過程名稱功能描述輸入輸出及返回值說明調(diào)用關(guān)系及被調(diào)用關(guān)系說明等。 前言 推薦Google的Java編碼規(guī)范英文版： http://google-styleguide.googlecode.com/svn/trunk/javaguide.html 雖然...
摘要：前言作為一名全干打字員，干活時經(jīng)常會被要求使用各種各樣的語言去實現(xiàn)各種各樣的需求，來回切換起來寫的代碼就會或多或少有點不規(guī)范。今天我們以為例，講講在代碼中，我們需要注意的某些規(guī)范。 前言 作為一名全干打字員，干活時經(jīng)常會被要求使用各種各樣的語言去實現(xiàn)各種各樣的需求，來回切換起來寫的代碼就會或多或少有點不規(guī)范。今天我們以JAVA為例，講講在代碼中，我們需要注意的某些規(guī)范。（本文標(biāo)準(zhǔn)依賴于...
摘要：對變量對象或者函數(shù)等進(jìn)行命名時，選擇能清晰表達(dá)其用途的名字。其實，測試方法名應(yīng)該明確指出測試的內(nèi)容與條件。和這種命名方式是時代的前朝遺物。使用自己的異常類型筆者又一次錯誤地認(rèn)為這一開發(fā)習(xí)慣是業(yè)內(nèi)的共識。 作為 Java 開發(fā)人員，我們會遵循一系列的編碼風(fēng)格和開發(fā)習(xí)慣。習(xí)慣使然是一方面，另一方面，我們也從不停下腳步質(zhì)疑這些習(xí)慣。一段時間以后，筆者養(yǎng)成了一些不同于常人的編碼風(fēng)格和開發(fā)習(xí)慣。...
閱讀 2702·2023-04-26 00:07
閱讀 2458·2021-11-15 11:37
閱讀 678·2021-10-19 11:44
閱讀 2203·2021-09-22 15:56
閱讀 1767·2021-09-10 10:50
閱讀 1530·2021-08-18 10:21
閱讀 2597·2019-08-30 15:53
閱讀 1656·2019-08-30 11:11
