1、在軟件開(kāi)發(fā)的過(guò)程中總是強(qiáng)調(diào)注釋的規(guī)范，但是沒(méi)有一個(gè)具體的標(biāo)準(zhǔn)進(jìn)行說(shuō)明，通常都是在代碼編寫(xiě)規(guī)范中簡(jiǎn)單的描述幾句，不能作為一個(gè)代碼注釋檢查的標(biāo)準(zhǔn)和依據(jù)，做什么都要有一個(gè)依據(jù)嗎：）,現(xiàn)在我特整理了一個(gè)Java的注釋規(guī)范，內(nèi)容來(lái)自網(wǎng)絡(luò)、書(shū)籍和自己的實(shí)際 積累。JAVA注釋規(guī)范版本/狀態(tài)作者版本日期1.0 ghc 2008-07-02一、背景1、當(dāng)我們第一次接觸某段代碼，但又被要求在極短的時(shí)間內(nèi)有效地分析這段代碼，我們需 要什么樣的注釋信息？2、怎么樣避免我們的注釋冗長(zhǎng)而且凌亂不堪呢？3、在多人協(xié)同開(kāi)發(fā)、維護(hù)的今天，我們需要怎么樣的注釋來(lái)保證高質(zhì)、高交的進(jìn)行開(kāi)發(fā)和 維護(hù)工作呢？二、意義程序中的注釋是程序

2、設(shè)計(jì)者與程序閱讀者之間通信的重要手段。應(yīng)用注釋規(guī)范對(duì)于軟件本身和軟件開(kāi)發(fā)人員而言尤為重要。并且在流行的敏捷開(kāi)發(fā)思想中已經(jīng)提出了將注釋轉(zhuǎn)為代碼的 概念。好的注釋規(guī)范可以盡可能的減少一個(gè)軟件的維護(hù)成本，并且?guī)缀鯖](méi)有任何一個(gè)軟件，在其整個(gè)生命周期中，均由最初的開(kāi)發(fā)人員來(lái)維護(hù)。好的注釋規(guī)范可以改善軟件的可讀性， 可以讓開(kāi)發(fā)人員盡快而徹底地理解新的代碼。好的注釋規(guī)范可以最大限度的提高團(tuán)隊(duì)開(kāi)發(fā)的合作效率。長(zhǎng)期的規(guī)范性編碼還可以讓開(kāi)發(fā)人員養(yǎng)成良好的編碼習(xí)慣，甚至鍛煉出更加嚴(yán)謹(jǐn)?shù)乃季S能力。三、注釋的原則1、注釋形式統(tǒng)一在整個(gè)應(yīng)用程序中，使用具有一致的標(biāo)點(diǎn)和結(jié)構(gòu)的樣式來(lái)構(gòu)造注釋。如果在其他項(xiàng)目組發(fā)現(xiàn)他們的注釋規(guī)

3、范與這份文檔不同，按照他們的規(guī)范寫(xiě)代碼， 不要試圖在既成的規(guī)范系統(tǒng)中引入新的規(guī)范。2、注釋的簡(jiǎn)潔內(nèi)容要簡(jiǎn)單、明了、含義準(zhǔn)確，防止注釋的多義性，錯(cuò)誤的注釋不但無(wú)益反而有害。3、注釋的一致性在寫(xiě)代碼之前或者邊寫(xiě)代碼邊寫(xiě)注釋， 因?yàn)橐院蠛芸赡軟](méi)有時(shí)間來(lái)這樣做。 另外，如果有機(jī) 會(huì)復(fù)查已編寫(xiě)的代碼， 在今天看來(lái)很明顯的東西六周以后或許就不明顯了。通常描述性注釋先于代碼創(chuàng)建，解釋性注釋在開(kāi)發(fā)過(guò)程中創(chuàng)建， 提示性注釋在代碼完成之后創(chuàng)建。 修改代碼 的同時(shí)修改相應(yīng)的注釋，以保證代碼與注釋的同步。4、注釋的位置保證注釋與其描述的代碼相鄰， 即注釋的就近原則。對(duì)代碼的注釋?xiě)?yīng)放在其上方相鄰或右方 的位置，不可放在

4、下方。 避免在代碼行的末尾添加注釋； 行尾注釋使代碼更難閱讀。不過(guò)在 批注變量聲明時(shí)，行尾注釋是合適的；在這種情況下，將所有行尾注釋要對(duì)齊。5、注釋的數(shù)量注釋必不可少，但也不應(yīng)過(guò)多，在實(shí)際的代碼規(guī)范中， 要求注釋占程序代碼的比例達(dá)到20%左右。注釋是對(duì)代碼的“提示”，而不是文檔，程序中的注釋不可喧賓奪主，注釋太多了會(huì) 讓人眼花繚亂，注釋的花樣要少。不要被動(dòng)的為寫(xiě)注釋而寫(xiě)注釋。6、刪除無(wú)用注釋在代碼交付或部署發(fā)布之前，必須刪掉臨時(shí)的或無(wú)關(guān)的注釋，以避免在日后的維護(hù)工作中產(chǎn)生混亂。7、復(fù)雜的注釋如果需要用注釋來(lái)解釋復(fù)雜的代碼，請(qǐng)檢查此代碼以確定是否應(yīng)該重寫(xiě)它。盡一切可能不注釋難以理解的代碼，而應(yīng)該

5、重寫(xiě)它。盡管一般不應(yīng)該為了使代碼更簡(jiǎn)單便于使用而犧牲性能， 但必須保持性能和可維護(hù)性之間的平衡。8、多余的注釋描述程序功能和程序各組成部分相互關(guān)系的高級(jí)注釋是最有用的，而逐行解釋程序如何工作的低級(jí)注釋則不利于讀、寫(xiě)和修改，是不必要的，也是難以維護(hù)的。避免每行代碼都使用注釋。如果代碼本來(lái)就是清楚、一目了然的則不加注釋，避免多余的或不適當(dāng)?shù)淖⑨尦霈F(xiàn)。9、必加的注釋典型算法必須有注釋。在代碼不明晰或不可移植處必須有注釋。在代碼修改處加上修改標(biāo)識(shí)的注釋。在循環(huán)和邏輯分支組成的代碼中添加注釋。為了防止問(wèn)題反復(fù)出現(xiàn)，對(duì)錯(cuò)誤修復(fù)和解決方法的代碼使用注釋，尤其是在團(tuán)隊(duì)環(huán)境中。10、注釋在編譯代碼時(shí)會(huì)被忽略，不

6、編譯到最后的可執(zhí)行文件中，所以注釋不 會(huì)增加可執(zhí)行文件的大小。四、JAVA注釋技巧1、空行和空白字符也是一種特殊注釋。利用縮進(jìn)和空行，使代碼與注釋容易區(qū) 別，并協(xié)調(diào)美觀。2、當(dāng)代碼比較長(zhǎng)，特別是有多重嵌套時(shí)，為了使層次清晰，應(yīng)當(dāng)在一些段落的 結(jié)束處加注釋（在閉合的右花括號(hào)后注釋該閉合所對(duì)應(yīng)的起點(diǎn)），注釋不能 寫(xiě)得很長(zhǎng)，只要能表示是哪個(gè)控制語(yǔ)句控制范圍的結(jié)束即可，這樣便于閱讀。3、將注釋與注釋分隔符用一個(gè)空格分開(kāi)，在沒(méi)有顏色提示的情況下查看注釋時(shí)， 這樣做會(huì)使注釋很明顯且容易被找到。4、不允許給塊注釋的周圍加上外框。這樣看起來(lái)可能很漂亮，但是難于維護(hù)。5、 每行注釋（連同代碼）不要超過(guò) 120個(gè)

7、字（1024 X 768），最好不要超過(guò) 80字（800 X 600）。6、 Java編輯器（IDE ）注釋快捷方式。Ctrl+/注釋當(dāng)前行，再按則取消注釋。7、 對(duì)于多行代碼的注釋，盡量不采用“/*/ ”，而采用多行“ /”注釋，這樣雖然麻煩，但是在做屏蔽調(diào)試時(shí)不用查找配對(duì)的“/*/ ”。8、注釋作為代碼切換開(kāi)關(guān)，用于臨時(shí)測(cè)試屏蔽某些代碼。例一：/*/codeSegeme nt1;/*/改動(dòng)第一行就成了：/*/codeSegeme nt1;/*/例二：/第一段有效，第二段被注釋/*/codeSegeme nt1;/*/codeSegeme nt2;11*1只需刪除第一行的/就可以變成：II第

8、一段被注釋，第二段有效/*/codeSegeme ntl;/*/codeSegeme nt2;/*/五、JAVA注釋方法及格式1、單行(single-line)-短注釋：/單獨(dú)行注釋：在代碼中單起一行注釋，注釋前最好有一行空行，并與其后的代碼具有一樣的縮進(jìn)層級(jí)。如果單行無(wú)法完成，則應(yīng)采用塊注釋。注釋格式：/*注釋內(nèi)容*/行頭注釋：在代碼行的開(kāi)頭進(jìn)行注釋。主要為了使該行代碼失去意義。注釋格式：注釋內(nèi)容行尾注釋：尾端(trailing)-極短的注釋，在代碼行的行尾進(jìn)行注釋。一般與代碼行后空8 (至少4)個(gè)格，所有注釋必須對(duì)齊。注釋格式：代碼+ 8 (至少4)個(gè)空格+ /注釋內(nèi)容2、塊(block)

9、-塊注釋：/*/注釋若干行，通常用于提供文件、方法、數(shù)據(jù)結(jié)構(gòu)等的意義與用途的說(shuō)明，或者算法的描述。一般位于一個(gè)文件或者一個(gè)方法的前面，起到引導(dǎo)的作用，也可以根據(jù)需要放在合適的位置。這種域注釋不會(huì)出現(xiàn)在HTML報(bào)告中。注釋格式通常寫(xiě)成：/*注釋內(nèi)容*/3、文檔注釋：/*/注釋若干行，并寫(xiě)入javadoc文檔。每個(gè)文檔注釋都會(huì)被置于注釋定界符/*/之中，注釋文檔將用來(lái)生成HTML格式的代碼報(bào)告，所以注釋文檔必須書(shū)寫(xiě)在類、域、構(gòu)造函數(shù)、方法，以及字段(field)定義之前。注釋文檔由兩部分組成描述、塊標(biāo)記。注釋文檔的格式如下：/* The doGet method of the servlet.*

10、This method is called whe n a form has its tag value method* equals to get.* param request* the request send by the clie nt to the server* param response* the resp onse send by the server to the clie nt* throws ServletExcepti on* if an error occurred* throws IOExceptio nif an error occurred*/ public

11、 void doGet (HttpServletRequest request, HttpServletResp onse resp onse) throws ServletExcepti on, I OExcepti on doPost（request, resp on se）;前兩行為描述，描述完畢后，由符號(hào)起頭為塊標(biāo)記注釋。更多有關(guān)文檔注釋禾口 javadoc 的詳纟田資料，參見(jiàn) javadoc 的主頁(yè)： 4、javadoc注釋標(biāo)簽語(yǔ)法author對(duì)類的說(shuō)明標(biāo)明開(kāi)發(fā)該類模塊的作者version對(duì)類的說(shuō)明標(biāo)明該類模塊的版本see對(duì)類、屬性、方法的說(shuō)明 參考轉(zhuǎn)向，也就是相關(guān)主題param對(duì)方

12、法的說(shuō)明 對(duì)方法中某參數(shù)的說(shuō)明return對(duì)方法的說(shuō)明 對(duì)方法返回值的說(shuō)明exception對(duì)方法的說(shuō)明對(duì)方法可能拋出的異常進(jìn)行說(shuō)明六、JAVA注釋具體實(shí)現(xiàn)1源文件注釋源文件注釋采用 /*/，在每個(gè)源文件的頭部要有必要的注釋信息，包括：文件名； 文件編號(hào)；版本號(hào)；作者；創(chuàng)建時(shí)間；文件描述包括本文件歷史修改記錄等。中文注釋模版:/* *文件名：* CopyRright (c) 2008-xxxx:文件牛編口 號(hào):創(chuàng)建人：日期:修改人：日期:描述：版本號(hào):*/ 2、類（模塊）注釋：類（模塊）注釋采用 /*/，在每個(gè)類（模塊）的頭部要有必要的注釋信息，包括：工程名；類（模塊）編號(hào)；命名空間；類可以運(yùn)

13、行的JDK版本；版本號(hào)；作者；創(chuàng)建時(shí)間；類（模塊）功能描述（如功能、主要算法、內(nèi)部各部分之間的關(guān)系、該類與其類的關(guān)系等，必要時(shí)還要有一些如特別的軟硬件要求等說(shuō)明）；主要函數(shù)或過(guò)程清單及本類（模塊）歷史修改記錄等。英文注釋模版：* CopyRright （c）2008-xxxx:<展望軟件 Forsoft >* Project:<項(xiàng)目工程名 >* Module ID:<（模塊）類編號(hào)，可以引用系統(tǒng)設(shè)計(jì)中的類編號(hào)>* Comme nts:<對(duì)此類的描述，可以引用系統(tǒng)設(shè)計(jì)中的描述>* JDK version used:<JDK1.6>* N

14、amespace:<命名空間 >* Author :<作者中文名或拼音縮寫(xiě) >* Create Date :<創(chuàng)建日期，格式：YYYY-MM-DD>* Modified By :<修改人中文名或拼音縮寫(xiě) >* Modified Date:<修改日期，格式：YYYY-MM-DD>* Why & What is modified<修改原因描述 >* Version:<版本號(hào) >*/如果模塊只進(jìn)行部分少量代碼的修改時(shí)，則每次修改須添加以下注釋：/Rewriter/Rewrite Date : <修改日期

15、：格式 YYYY-MM-DD> Start1 :/*原代碼內(nèi)容*/End1:將原代碼內(nèi)容注釋掉，然后添加新代碼使用以下注釋：/Added by/Add date : <添加日期，格式： YYYY-MM-DD> Start2 :End2:如果模塊輸入輸出參數(shù)或功能結(jié)構(gòu)有較大修改，則每次修改必須添加以下 注釋：/Log ID : <Log編號(hào)，從1開(kāi)始一次增加>/Depiction : <對(duì)此修改的描述 >/Writer:修改者中文名/Rewrite Date : <模塊修改日期，格式：YYYY-MM-DD>2、接口注釋：接口注釋采用/*/，在

16、滿足類注釋的基礎(chǔ)之上，接口注釋?xiě)?yīng)該包含描述接口的目的、它應(yīng)如何被使用以及如何不被使用，塊標(biāo)記部分必須注明作者和版本。在接口注釋清楚的前提下對(duì)應(yīng)的實(shí)現(xiàn)類可以不加注釋。3、構(gòu)造函數(shù)注釋:構(gòu)造函數(shù)注釋采用/*/，描述部分注明構(gòu)造函數(shù)的作用，不一定有塊標(biāo)記部分。注釋模版一:*默認(rèn)構(gòu)造函數(shù)*/注釋模版二：/* Descriptio n :帶參數(shù)構(gòu)造函數(shù)，*初始化模式名，名稱和數(shù)據(jù)源類型* param schema :模式名* param n ame :名稱* param type : 數(shù)據(jù)源類型*/4、函數(shù)注釋：函數(shù)注釋采用 /*/，在每個(gè)函數(shù)或者過(guò)程的前面要有必要的注釋信息，包括：函數(shù) 或過(guò)程名稱；功

17、能描述；輸入、輸出及返回值說(shuō)明；調(diào)用關(guān)系及被調(diào)用關(guān)系說(shuō)明等。函數(shù)注釋里面可以不出現(xiàn)版本號(hào)（version ）。注釋模版一:/*函數(shù)名：*功能描述：*輸入?yún)?shù):按照參數(shù)定義順序*param后面空格后跟著參數(shù)的變量名字（不是類型），空格后跟著對(duì)該參數(shù)的描述。*返回值:-類型 說(shuō)明*返回為空（void ）的構(gòu)造函數(shù)或者函數(shù)，*return可以省略；如果返回值就是輸入?yún)?shù)，必須*用與輸入?yún)?shù)的param相同的描述信息；必要的時(shí)*候注明特殊條件寫(xiě)的返回值。*異 常： 按照異常名字的字母順序*創(chuàng)建人：*日期：*修改人：*日期：*/注釋模版二：/* Fun Name:getFirstSpell* Description :獲取漢字拼音首字母的字符串，* 被生成百家姓函數(shù)調(diào)用* param :str the String是包含漢字的字符串* return String :漢字返回拼音首字母字符串；* 英文字母返回對(duì)應(yīng)的大寫(xiě)字母；* 其他非簡(jiǎn)體漢字返回'0'；* Author:ghc* Create Date: 2008-07-02*/5、方法注釋：方法注釋采用/*/，對(duì)于設(shè)置（Set方法）與獲取（Get方法）成員的方法，在成 員變量已有說(shuō)明的情