java快捷鍵和註釋規範

寫了那麼久java了，到現在才有意識地規範程式碼註釋，以下內容大部分參考gyhgc的部落格。

註釋常用的快捷鍵：

1.//ctrl+/

2./*……*/ 先敲/*再敲回車

3./**……*/ 先敲/**再敲回車

一、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);

}

前兩行為描述，描述完畢後，由@符號起頭為塊標記註釋。

4、javadoc註釋標籤語法

@author 對類的說明標明開發該類模組的作者

@version 對類的說明標明該類模組的版本

@see 對類、屬性、方法的說明參考轉向，也就是相關主題

@param 對方法的說明對方法中某引數的說明

@return 對方法的說明對方法返回值的說明

@exception 對方法的說明對方法可能丟擲的異常進行說明

二、JAVA註釋具體實現

1、原始檔註釋

原始檔註釋採用 /** …… */，在每個原始檔的頭部要有必要的註釋資訊，包括：檔名；檔案編號；版本號；作者；建立時間；檔案描述包括本檔案歷史修改記錄等。中文註釋模版：

/**

* 文件名 :

* 檔案編號：

* 創建人：

* 日期：

* 修改人：

* 日期：

* 描述：

* 版本號：

*/

2、類（模組）註釋：

類（模組）註釋採用 /** …… */，在每個類（模組）的頭部要有必要的註釋資訊，包括：工程名；類（模組）編號；名稱空間；類可以執行的JDK版本；版本號；作者；建立時間；類（模組）功能描述（如功能、主要演算法、內部各部分之間的關係、該類與其類的關係等，必要時還要有一些如特別的軟硬體要求等說明）；主要函式或過程清單及本類（模組）歷史修改記錄等。

英文註釋模版：

/**

* 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快捷鍵和註釋規範

相關文章