一、前言

好的程式碼規範是一個程式設計師的基本修煉，好的程式碼註釋更能體現一個程式設計師的思維邏輯，雖然程式碼是用來給機器執行的，我們只要能寫出能讓編譯器執行的程式碼就行了，但是如果沒有好的編碼規範，到專案後期，加入開發的人員逐漸增多時，每個人的編碼風格都不一樣，這就會讓專案維護者很難維護，所以開始就要制定一些好的規範來讓大家遵守，這樣才能寫出可維護，健壯的專案，這就是接下來要做的事情。第一節從要從程式碼註釋這一塊說起，包含: 版權註釋、類註釋(Class)、建構函式註釋(Constructor)、方法註釋(Methods)、程式碼塊註釋(Block)、單句註釋、欄位名註釋，然後分別為eclipse、IDEA建立註釋模組等。

二、約定

下面就是一些常見的註釋示例:

1、版權註釋

版權註釋主要用來宣告公司的一些基本資訊等:

1. /**   
2.  * projectName: xxx  
3.  * fileName: Tk.java   
4.  * packageName: xxxx  
5.  * date: 2017年12月18日下午12:28:39   
6.  * copyright(c) 2017-2020 xxx公司  
7.  */  

2、類註釋(Class)

類註釋(Class)主要用來宣告該類用來做什麼，以及建立者、建立日期版本、包名等一些資訊:

1. /**  
2.  * @version: V1.0  
3.  * @author: fendo  
4.  * @className: user  
5.  * @packageName: user  
6.  * @description: 這是使用者類  
7.  * @data: 2017-07-28 12:20  
8.  **/  

3、建構函式註釋(Constructor)

建構函式註釋(Constructor)主要用來宣告該類的建構函式、入參等資訊:

1. **  
2. * @description: 建構函式  
3. * @param: [sid, pid]  
4. */    

4、方法註釋(Methods)

方法註釋(Methods)主要用來宣告該類的作用、入參、返回值、異常等資訊:

1. /**  
2. * @author:  fendo  
3. * @methodsName: addUser  
4. * @description: 新增一個使用者  
5. * @param:  xxxx  
6. * @return: String  
7. * @throws:   
8. */  

5、程式碼塊註釋(Block)

1. /**  
2.  * 例項化一個使用者  
3.  * xxxxxxx  
4.  */  
5. User user=new User();  

6、單句註釋

1. User user=new User();  //例項化一個使用者  

7、欄位名註釋

1. /**  
2.  * 使用者名稱  
3.  */  
4. public String name;  

或者使用如下格式:

1. /**使用者名稱**/  
2. public String name;  

三、IDE模板

接下來就是分別在Eclipse和IDEA中實現上面的註釋，然後分別生成模板:

3.1、Eclipse程式碼註釋

在Eclipse中可以通過CodeTemplates進行設定，具體步驟如下: Window->Preference->Java->Code Style->Code Template 

其中有兩類一類是Comments、主要是類中的一些通用模板:

1.檔案(Files)註釋標籤：

設定版權資訊:

1. /**   
2.  * projectName: ${project_name}   
3.  * fileName: ${file_name}   
4.  * packageName: ${package_name}   
5.  * date: ${date}${time}   
6.  * copyright(c) 2017-2020 xxx公司  
7.  */  

注意: 要打上勾!!

2.型別(Types)註釋標籤(類的註釋)：

1. /**     
2.  * @title: ${file_name}   
3.  * @package ${package_name}   
4.  * @description: ${todo}  
5.  * @author: fendo  
6.  * @date: ${date} ${time}   
7.  * @version: V1.0     
8. */  

3.欄位(Fields)註釋標籤：

1. /**     
2.  * @Fields ${field} : ${todo}(用一句話描述這個變量表示什麼)     
3.  */    

4.建構函式(Constructors)標籤：

1. /**     
2.  * @title: ${enclosing_type}     
3.  * @description: ${todo}(這裡用一句話描述這個方法的作用)     
4.  * @param: ${tags}    
5.  * @throws:     
6.  */   

5.方法(Methods)標籤：

1. /**  
2.  *@title: ${enclosing_method}   
3.  *@description: ${todo}  
4.  *@author: fendo  
5.  *@date: ${date} ${time}  
6.  *${tags}  
7.  *@throws:   
8.  */   

6.覆蓋方法(Overriding Methods)標籤:

1. /**     
2.  * @title: ${enclosing_method}  
3.  * @description: ${todo}  
4.  * ${tags}     
5.  * ${see_to_overridden}       
6.  */   

7.代表方法(Delegate Methods)標籤：

1. /**    
2.  * ${tags}    
3.  * ${see_to_target}    
4.  */    

8.Getter方法標籤：

1. /**    
2.  * @title: ${enclosing_method}  
3.  * @description: ${todo}  
4.  * @return: ${field_type}  
5.  */       

9.Setter方法標籤：

1. /**    
2.  * @title: ${enclosing_method}  
3.  * @description: ${todo}  
4.  * @return: ${field_type}  
5.  */  

另一類是程式碼模板如下: