java程式碼註釋規範(二)
一、背景
1、當我們第一次接觸某段程式碼,但又被要求在極短的時間內有效地分析這段程式碼,我們需要什麼樣的註釋資訊?
2、怎麼樣避免我們的註釋冗長而且凌亂不堪呢?
3、在多人協同開發、維護的今天,我們需要怎麼樣的註釋來保證高質、高交的進行開發和維護工作呢?
二、意義
程式中的註釋是程式設計者與程式閱讀者之間通訊的重要手段。應用註釋規範對於軟體本身和軟體開發人員而言尤為重要。並且在流行的敏捷開發思想中已經提出了將註釋轉為程式碼的概念。好的註釋規範可以儘可能的減少一個軟體的維護成本 , 並且幾乎沒有任何一個軟體,在其整個生命週期中,均由最初的開發人員來維護。好的註釋規範可以改善軟體的可讀性,可以讓開發人員儘快而徹底地理解新的程式碼。好的註釋規範可以最大限度的提高團隊開發的合作效率。長期的規範性編碼還可以讓開發人員養成良好的編碼習慣,甚至鍛煉出更加嚴謹的思維能力。
三、註釋的原則
1、 註釋形式統一
在整個應用程式中,使用具有一致的標點和結構的樣式來構造註釋。如果在其他專案組發現他們的註釋規範與這份文件不同,按照他們的規範寫程式碼,不要試圖在既成的規範系統中引入新的規範。
2、 註釋的簡潔
內容要簡單、明瞭、含義準確,防止註釋的多義性,錯誤的註釋不但無益反而有害。
3、 註釋的一致性
在寫程式碼之前或者邊寫程式碼邊寫註釋,因為以後很可能沒有時間來這樣做。另外,如果有機會複查已編寫的程式碼,在今天看來很明顯的東西六週以後或許就不明顯了。通常描述性註釋先於程式碼建立,解釋性註釋在開發過程中建立,提示性註釋在程式碼完成之後建立。修改程式碼的同時修改相應的註釋,以保證程式碼與註釋的同步。
4、 註釋的位置
保證註釋與其描述的程式碼相鄰,即註釋的就近原則。對程式碼的註釋應放在其上方相鄰或右方的位置,不可放在下方。避免在程式碼行的末尾添加註釋;行尾註釋使程式碼更難閱讀。不過在批註變數宣告時,行尾註釋是合適的;在這種情況下,將所有行尾註釋要對齊。
5、 註釋的數量
註釋必不可少,但也不應過多,在實際的程式碼規範中,要求註釋佔程式程式碼的比例達到20%左右。註釋是對程式碼的“提示”,而不是文件,程式中的註釋不可喧賓奪主,註釋太多了會讓人眼花繚亂,註釋的花樣要少。不要被動的為寫註釋而寫註釋。
6、刪除無用註釋
在程式碼交付或部署釋出之前,必須刪掉臨時的或無關的註釋,以避免在日後的維護工作中產生混亂。
7、 複雜的註釋
如果需要用註釋來解釋複雜的程式碼,請檢查此程式碼以確定是否應該重寫它。盡一切可能不註釋難以理解的程式碼,而應該重寫它。儘管一般不應該為了使程式碼更簡單便於使用而犧牲效能,但必須保持效能和可維護性之間的平衡。
8、 多餘的註釋
描述程式功能和程式各組成部分相互關係的高階註釋是最有用的,而逐行解釋程式如何工作的低階註釋則不利於讀、寫和修改,是不必要的,也是難以維護的。避免每行程式碼都使用註釋。如果程式碼本來就是清楚、一目瞭然的則不加註釋,避免多餘的或不適當的註釋出現。
9、必加的註釋
典型演算法必須有註釋。在程式碼不明晰或不可移植處必須有註釋。在程式碼修改處加上修改標識的註釋。在迴圈和邏輯分支組成的程式碼中添加註釋。為了防止問題反覆出現,對錯誤修復和解決方法的程式碼使用註釋,尤其是在團隊環境中。
10、註釋在編譯程式碼時會被忽略,不編譯到最後的可執行檔案中,所以註釋不
會增加可執行檔案的大小。
四、JAVA註釋技巧
1、空行和空白字元也是一種特殊註釋。利用縮排和空行,使程式碼與註釋容易區
別,並協調美觀。
2、當代碼比較長,特別是有多重巢狀時,為了使層次清晰,應當在一些段落的
結束處加註釋(在閉合的右花括號後註釋該閉合所對應的起點),註釋不能
寫得很長,只要能表示是哪個控制語句控制範圍的結束即可,這樣便於閱讀。
3、將註釋與註釋分隔符用一個空格分開,在沒有顏色提示的情況下檢視註釋時,
這樣做會使註釋很明顯且容易被找到。
4、不允許給塊註釋的周圍加上外框。這樣看起來可能很漂亮,但是難於維護。
5、每行註釋(連同程式碼)不要超過120個字(1024×768),最好不要超過80
字(800×600) 。
6、Java編輯器(IDE)註釋快捷方式。Ctrl+/ 註釋當前行,再按則取消註釋。
7、對於多行程式碼的註釋,儘量不採用“/*......*/”,而採用多行“//”註釋,
這樣雖然麻煩,但是在做遮蔽除錯時不用查詢配對的“/*......*/”。
8、註釋作為程式碼切換開關,用於臨時測試遮蔽某些程式碼。
例一:
//*/
codeSegement1;
//*/
改動第一行就成了:
/*/
codeSegement1;
//*/
例二:
//----------------------第一段有效,第二段被註釋
//*/
codeSegement1;
/*/
codeSegement2;
//*/
只需刪除第一行的/就可以變成:
//----------------------第一段被註釋,第二段有效
/*/
codeSegement1;
/*/
codeSegement2;
//*/
五、JAVA註釋方法及格式
1、單行(single-line)--短註釋://……
單獨行註釋:在程式碼中單起一行註釋, 註釋前最好有一行空行,並與其後的程式碼具有一樣的縮排層級。如果單行無法完成,則應採用塊註釋。
註釋格式:/* 註釋內容 */
行頭註釋:在程式碼行的開頭進行註釋。主要為了使該行程式碼失去意義。
註釋格式:// 註釋內容
行尾註釋:尾端(trailing)--極短的註釋,在程式碼行的行尾進行註釋。一般與程式碼行後空8(至少4)個格,所有註釋必須對齊。
註釋格式:程式碼 + 8(至少4)個空格 + // 註釋內容
2、塊(block)--塊註釋:/*……*/
註釋若干行,通常用於提供檔案、方法、資料結構等的意義與用途的說明,或者演算法的描述。一般位於一個檔案或者一個方法的前面,起到引導的作用,也可以根據需要放在合適的位置。這種域註釋不會出現在HTML報告中。註釋格式通常寫成:
/*
* 註釋內容
*/
3、文件註釋:/**……*/
註釋若干行,並寫入javadoc文件。每個文件註釋都會被置於註釋定界符
/**......*/之中,註釋文件將用來生成HTML格式的程式碼報告,所以註釋文
檔必須書寫在類、域、建構函式、方法,以及欄位(field)定義之前。註釋文件由兩部分組成——描述、塊標記。註釋文件的格式如下:
/**
* The doGet method of the servlet.
* This method is called when a form has its tag value method
* equals to get.
* @param request
* the request send by the client to the server
* @param response
* the response send by the server to the client
* @throws ServletException
* if an error occurred
* @throws IOException
* if an error occurred
*/
public void doGet (HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
doPost(request, response);
}
前兩行為描述,描述完畢後,由@符號起頭為塊標記註釋。更多有關文件注
釋和javadoc的詳細資料,參見javadoc的主頁: http://java.sun.com/javadoc/index.html
4、javadoc註釋標籤語法
@author 對類的說明 標明開發該類模組的作者
@version 對類的說明 標明該類模組的版本
@see 對類、屬性、方法的說明 參考轉向,也就是相關主題
@param 對方法的說明 對方法中某引數的說明
@return 對方法的說明 對方法返回值的說明
@exception 對方法的說明 對方法可能丟擲的異常進行說明
六、JAVA註釋具體實現
1、原始檔註釋
原始檔註釋採用 /** …… */,在每個原始檔的頭部要有必要的註釋資訊,包括:檔名;檔案編號;版本號;作者;建立時間;檔案描述包括本檔案歷史修改記錄等。中文註釋模版:
/**
* 文 件 名 :
* CopyRright (c) 2008-xxxx:
* 檔案編號:
* 創 建 人:
* 日 期:
* 修 改 人:
* 日 期:
* 描 述:
* 版 本 號:
*/
2、類(模組)註釋:
類(模組)註釋採用 /** …… */,在每個類(模組)的頭部要有必要的註釋資訊,包括:工程名;類(模組)編號;名稱空間;類可以執行的JDK版本;版本號;作者;建立時間;類(模組)功能描述(如功能、主要演算法、內部各部分之間的關係、該類與其類的關係等,必要時還要有一些如特別的軟硬體要求等說明);主要函式或過程清單及本類(模組)歷史修改記錄等。
英文註釋模版:
/**
* CopyRright (c)2008-xxxx: <展望軟體Forsoft >
* Project: <專案工程名 >
* Module ID: <(模組)類編號,可以引用系統設計中的類編號>
* Comments: <對此類的描述,可以引用系統設計中的描述>
* JDK version used: <JDK1.6>
* Namespace: <名稱空間>
* Author: <作者中文名或拼音縮寫>
* Create Date: <建立日期,格式:YYYY-MM-DD>
* Modified By: <修改人中文名或拼音縮寫>
* Modified Date: <修改日期,格式:YYYY-MM-DD>
* Why & What is modified <修改原因描述>
* Version: <版本號>
*/
如果模組只進行部分少量程式碼的修改時,則每次修改須新增以下注釋:
//Rewriter
//Rewrite Date:<修改日期:格式YYYY-MM-DD> Start1:
/* 原始碼內容*/
//End1:
將原始碼內容註釋掉,然後新增新程式碼使用以下注釋:
//Added by
//Add date:<新增日期,格式:YYYY-MM-DD> Start2:
//End2:
如果模組輸入輸出引數或功能結構有較大修改,則每次修改必須新增以下
註釋:
//Log ID:<Log編號,從1開始一次增加>
//Depiction:<對此修改的描述>
//Writer:修改者中文名
//Rewrite Date:<模組修改日期,格式:YYYY-MM-DD>
2、介面註釋:
介面註釋採用 /** …… */,在滿足類註釋的基礎之上,介面註釋應該包含描述介面的目的、它應如何被使用以及如何不被使用,塊標記部分必須註明作者和版本。在介面註釋清楚的前提下對應的實現類可以不加註釋。
3、建構函式註釋:
建構函式註釋採用 /** …… */,描述部分註明建構函式的作用,不一定有塊標記部分。
註釋模版一:
/**
* 預設建構函式
*/
註釋模版二:
/**
* Description : 帶引數建構函式,
* 初始化模式名,名稱和資料來源型別
* @param schema: 模式名
* @param name: 名稱
* @param type: 資料來源型別
*/
4、函式註釋:
函式註釋採用 /** ……*/,在每個函式或者過程的前面要有必要的註釋資訊,包括:函式或過程名稱;功能描述;輸入、輸出及返回值說明;呼叫關係及被呼叫關係說明等。函式註釋裡面可以不出現版本號(@version)。
註釋模版一:
/**
* 函 數 名 :
* 功能描述:
* 輸入引數: <按照引數定義順序>
* <@param後面空格後跟著引數的變數名字
* (不是型別),空格後跟著對該引數的描述。>
*
* 返 回 值: - 型別 <說明>
* <返回為空(void)的建構函式或者函式,
* @return可以省略; 如果返回值就是輸入引數,必須 * 用與輸入引數的@param相同的描述資訊; 必要的時* 候註明特殊條件寫的返回值。>
* 異 常:<按照異常名字的字母順序>
* 創 建 人:
* 日 期:
* 修 改 人:
* 日 期:
*/
註釋模版二:
/**
* FunName: getFirstSpell
* Description : 獲取漢字拼音首字母的字串,
* 被生成百家姓函式呼叫
* @param: str the String是包含漢字的字串
* @return String:漢字返回拼音首字母字串;
* 英文字母返回對應的大寫字母;
* 其他非簡體漢字返回 '0';
* @Author: ghc
* @Create Date: 2008-07-02
*/
5、方法註釋:
方法註釋採用 /** …… */,對於設定 (Set 方法 ) 與獲取 (Get 方法 ) 成員的方法,在成員變數已有說明的情況下,可以不加註釋;普通成員方法要求說明完成什麼功能,引數含義是什麼且返回值什麼;另外方法的建立時間必須註釋清楚,為將來的維護和閱讀提供寶貴線索。
6、方法內部註釋:
控制結構,程式碼做了些什麼以及為什麼這樣做,處理順序等,特別是複雜的邏輯處理部分,要儘可能的給出詳細的註釋。
7、 全域性變數註釋:
要有較詳細的註釋,包括對其功能、取值範圍、哪些函式或者過程存取以及存取時注意事項等的說明。
8、區域性(中間)變數註釋:
主要變數必須有註釋,無特別意義的情況下可以不加註釋。
9、實參/引數註釋:
引數含義、及其它任何約束或前提條件。
10、欄位/屬性註釋: 欄位描述,屬性說明。
11、常量:常量通常具有一定的實際意義,要定義相應說明。
java 註釋有三種
1、// 註釋一行
2、/* ...... */ 註釋若干行
不完全對,除了以上兩種之外,還有第三種,文件註釋:
3、/** ...... */ 註釋若干行,並寫入 javadoc 文件 第三種形式主要是為了生成javadoc檔案,生成api用的.
----------------------------------------------------------------------------------------------------------------------------------------------
- 註釋要簡單明瞭。
//使用者名稱
String userName = null;
- 邊寫程式碼邊註釋,修改程式碼同時修改相應的註釋,以保證註釋與程式碼的一致性。
- 在必要的地方註釋,註釋量要適中。註釋的內容要清楚、明瞭,含義準確,防
止註釋二義性。保持註釋與其描述的程式碼相鄰,即註釋的就近原則。
- 對程式碼的註釋應放在其上方相鄰位置,不可放在下面。對資料結構的註釋應放在
其上方相鄰位置,不可放在下面;對結構中的每個域的註釋應放在此域的右方;
同一結構中不同域的註釋要對齊。(我沒用寫過域定義)
- 變數、常量的註釋應放在其上方相鄰位置或右方。
- 全域性變數要有較詳細的註釋,包括對其功能、取值範圍、哪些函式或過程存取它以
及存取時注意事項等的說明。
- 在每個原始檔的頭部要有必要的註釋資訊,包括:檔名;版本號;作者;生成日
期;模組功能描述(如功能、主要演算法、內部各部分之間的關係、該檔案與其它文
件關係等);主要函式或過程清單及本檔案歷史修改記錄等。
/**
* Copy Right Information : Neusoft IIT
* Project : eTrain
* JDK version used : jdk1.3.1
* Comments : config path
* Version : 1.01
* Modification history :2003.5.1
* Sr Date Modified By Why & What is modified
* 1. 2003.5.2 Kevin Gao new
**/
- 在每個函式或過程的前面要有必要的註釋資訊,包括:函式或過程名稱;功能描
述;輸入、輸出及返回值說明;呼叫關係及被呼叫關係說明等
/**
* Description :checkout 提款
* @param Hashtable cart info
* @param OrderBean order info
* @return String
*/
public String checkout(Hashtable htCart, OrderBean orderBean) throws Exception
{ }
- javadoc註釋標籤語法
@author 對類的說明 標明開發該類模組的作者
@version 對類的說明 標明該類模組的版本
@see 對類、屬性、方法的說明 參考轉向,也就是相關主題
@param 對方法的說明 對方法中某引數的說明
@type 對引數型別的說明
@return 對方法的說明 對方法返回值的說明
@exception 對方法的說明 對方法可能丟擲的異常進行說明
@other:其它說明
-----------------------------------------------------------------------------------------------
各公司都有不同要求,一般方法註釋需要註明該方法的作用,引數說明和返回值。有異常的要加異常說明。有時還要加上建立人,修改人和修改時間。一般這種註釋有 author parementer return Exception等
我在專案中用到了四種註釋(一個空格和Tab都不能多加,保證風格統一!)
1、包註釋
/****************************************************************************
*
* System Name :ACME_BANK_SYSTEM
* SubSystem Name:director
* ------- ------- ------- -------------- ------- ------- -------
*
* ClassNames:MG043E01SAction
* 利率設定Action,用於控制資料的走向。
*
* $Author Chu Yanwu $
* $Date 2008/11/28 $
* $RCSfile MG043E01SAction.java $
* $Revision 1.1 $
* (c) Copyright IBM JT10, Ltd. 2008.All rights reserved.
*
*
* Ver. Revision No.:JAVATEAM10
*
* Create Date/Changes History
* ------- ---------- ------------- ------------- ----------------- -----------------------------
* 1.0.0 1.1 - 2008/11/28 Chu Yanwu Creat MG043E01SAction.java
*
***************************************************************************/
2、類註釋
/**
* <pre>
* ClassNames:AccountNumberClass
* 用作自動生成賬號,通過使用者傳入的引數
* </pre>
*
* <UL>
* <LI>AccountNumberClass.java</LI>
* <LI>用作生成AccountNumberClass物件</LI>
* <LI>函式AccountNumberOccur(),過載1:以String型別為傳入引數</LI>
* <LI>函式AccountNumberOccur(),過載2:以int型別為傳入引數</LI>
* <LI>Page </LI>
* <LI>Author Chu Yanwu </LI>
* <LI>Version 1.0.0</LI>
* </UL>
* <DL>
* <DT><b></b></DT>
* <DD><BR>
* </DD>
* <BR>
* </DL>
*/
3、方法註釋
/**
* <pre>
* create the Number of Account
* </pre>
*
* @param type
* @type String
* @param accountType
* @type String
* @param workNo
* @type String
* @return accountNumber
* @type String
* @throws
*
* @other: 引數 String type 區段1:標示賬戶型別,0企業,1個人; 引數 String accountType
* 區段2:標示賬戶業務範圍及賬戶型別 引數 String workNo 區段3:標示職工號
*/
4、建構函式的註釋
/**
* create the Object of Logger
*
* @param
* @type
* @return logger
* @type Logger
* @throws
*/
5、欄位變數的註釋(行註釋)
// 1. Populate this dto
// 將form中的值賦值到model(dto)