Java代碼注釋規(guī)范(動(dòng)力節(jié)點(diǎn)整理)
代碼注釋是架起程序設(shè)計(jì)者與程序閱讀者之間的通信橋梁,最大限度的提高團(tuán)隊(duì)開(kāi)發(fā)合作效率。也是程序代碼可維護(hù)性的重要環(huán)節(jié)之一。所以我們不是為寫(xiě)注釋而寫(xiě)注釋。下面說(shuō)一下我們?cè)谌粘i_(kāi)發(fā)中使用的代碼注釋規(guī)范,供大家參考下。
1、 注釋形式統(tǒng)一
在整個(gè)應(yīng)用程序中,使用具有一致的標(biāo)點(diǎn)和結(jié)構(gòu)的樣式來(lái)構(gòu)造注釋。如果在其它項(xiàng)目中發(fā)現(xiàn)它們的注釋規(guī)范與這份文檔不同,按照這份規(guī)范寫(xiě)代碼,不要試圖在既成的規(guī)范系統(tǒng)中引入新的規(guī)范。
2、 注釋內(nèi)容準(zhǔn)確簡(jiǎn)潔
內(nèi)容要簡(jiǎn)單、明了、含義準(zhǔn)確,防止注釋的多義性,錯(cuò)誤的注釋不但無(wú)益反而有害。
注釋條件:
1、基本注釋
(a) 類(lèi)(接口)的注釋
(b) 構(gòu)造函數(shù)的注釋
(c) 方法的注釋
(d) 全局變量的注釋
(e) 字段/屬性的注釋
備注:簡(jiǎn)單的代碼做簡(jiǎn)單注釋?zhuān)⑨寖?nèi)容不大于10個(gè)字即可,另外,持久化對(duì)象或VO對(duì)象的getter、setter方法不需加注釋。具體的注釋格式請(qǐng)參考下面舉例。
2、特殊必加注釋
(a) 典型算法必須有注釋。
(b) 在代碼不明晰處必須有注釋。
(c) 在代碼修改處加上修改標(biāo)識(shí)的注釋。
(d) 在循環(huán)和邏輯分支組成的代碼中加注釋。
(e) 為他人提供的接口必須加詳細(xì)注釋。
備注:此類(lèi)注釋格式暫無(wú)舉例。具體的注釋格式自行定義,要求注釋內(nèi)容準(zhǔn)確簡(jiǎn)潔。
注釋格式:
1、單行(single-line)注釋?zhuān)?ldquo;//……”
2、塊(block)注釋?zhuān)?ldquo;/*……*/”
3、文檔注釋?zhuān)?ldquo;/**……*/”
4、javadoc 注釋標(biāo)簽語(yǔ)法
@author 對(duì)類(lèi)的說(shuō)明 標(biāo)明開(kāi)發(fā)該類(lèi)模塊的作者
@version 對(duì)類(lèi)的說(shuō)明 標(biāo)明該類(lèi)模塊的版本
@see 對(duì)類(lèi)、屬性、方法的說(shuō)明 參考轉(zhuǎn)向,也就是相關(guān)主題
@param 對(duì)方法的說(shuō)明 對(duì)方法中某參數(shù)的說(shuō)明
@return 對(duì)方法的說(shuō)明 對(duì)方法返回值的說(shuō)明
@exception 對(duì)方法的說(shuō)明 對(duì)方法可能拋出的異常進(jìn)行說(shuō)明
參考舉例:
1. 類(lèi)(接口)注釋
例如:
/** * 類(lèi)的描述 * @author Administrator * @Time 2016-11-14:49:01 * */ public classTest extends Button { …… }
2. 構(gòu)造方法注釋
例如:
public class Test extends Button { /** * 構(gòu)造方法 的描述 * @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;//發(fā)送人姓名 private String title;//不能超過(guò)120個(gè)中文字符 private String content;//郵件正文 private String attach;//附件,如果有的話 private String totalCount;//總發(fā)送人數(shù) private String successCount;//成功發(fā)送的人數(shù) private Integer isDelete;//0不刪除 1刪除 private Date createTime;//目前不支持定時(shí) 所以創(chuàng)建后即刻發(fā)送 privateSet<EmailList> EmailList; …… }
其實(shí)規(guī)范是自己訂的,只要團(tuán)隊(duì)中大家都統(tǒng)一遵守,統(tǒng)一規(guī)范,就會(huì)取得好的效果,希望對(duì)平時(shí)不加注釋的朋友有點(diǎn)幫助。
以上所述是小編給大家介紹的Java代碼注釋規(guī)范(動(dòng)力節(jié)點(diǎn)整理),希望對(duì)大家有所幫助,如果大家有任何疑問(wèn)請(qǐng)給我留言,小編會(huì)及時(shí)回復(fù)大家的。在此也非常感謝大家對(duì)腳本之家網(wǎng)站的支持!
相關(guān)文章
Spring boot + thymeleaf 后端直接給onclick函數(shù)賦值的實(shí)現(xiàn)代碼
這篇文章主要介紹了Spring boot + thymeleaf 后端直接給onclick函數(shù)賦值的實(shí)現(xiàn)代碼,需要的朋友可以參考下2017-06-06Java中final,finally,finalize三個(gè)關(guān)鍵字的區(qū)別_動(dòng)力節(jié)點(diǎn)Java學(xué)院整理
這篇文章給大家收集整理了有關(guān)java中final,finally,finalize三個(gè)關(guān)鍵字的區(qū)別介紹,非常不錯(cuò),具有參考借鑒價(jià)值,需要的的朋友參考下吧2017-04-04淺談java調(diào)用Restful API接口的方式
這篇文章主要介紹了淺談java調(diào)用Restful API接口的方式,具有一定借鑒價(jià)值,需要的朋友可以參考下。2017-12-12nacos客戶(hù)端一致性hash負(fù)載需求實(shí)現(xiàn)
這篇文章主要介紹了nacos客戶(hù)端一致性hash負(fù)載的需求實(shí)現(xiàn)過(guò)程及步驟詳解,有需要的朋友可以借鑒參考下,希望能夠有所幫助,祝大家多多進(jìn)步2022-02-02Java并發(fā)編程service層處理并發(fā)事務(wù)加鎖可能會(huì)無(wú)效問(wèn)題
這篇文章主要介紹了Java并發(fā)編程service層處理并發(fā)事務(wù)加鎖可能會(huì)無(wú)效問(wèn)題,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2023-07-07SpringMVC 攔截器不攔截靜態(tài)資源的三種處理方式方法
本篇文章主要介紹了SpringMVC 攔截器不攔截靜態(tài)資源的三種處理方式方法,詳細(xì)的介紹了三種方法,有興趣的可以了解一下。2017-01-01springboot整合netty框架實(shí)現(xiàn)站內(nèi)信
Netty 是一個(gè)基于NIO的客戶(hù)、服務(wù)器端編程框架,使用Netty 可以確保你快速和簡(jiǎn)單的開(kāi)發(fā)出一個(gè)網(wǎng)絡(luò)應(yīng)用,這篇文章主要介紹了springboot整合netty框架的方式小結(jié),需要的朋友可以參考下2022-12-12