編碼規範 之 ----JAVA註釋規範
一、前言
好的程式碼規範是一個程式設計師的基本修煉,好的程式碼註釋更能體現一個程式設計師的思維邏輯,雖然程式碼是用來給機器執行的,我們只要能寫出能讓編譯器執行的程式碼就行了,但是如果沒有好的編碼規範,到專案後期,加入開發的人員逐漸增多時,每個人的編碼風格都不一樣,這就會讓專案維護者很難維護,所以開始就要制定一些好的規範來讓大家遵守,這樣才能寫出可維護,健壯的專案,這就是接下來要做的事情。第一節從要從程式碼註釋這一塊說起,包含: 版權註釋、類註釋(Class)、建構函式註釋(Constructor)、方法註釋(Methods)、程式碼塊註釋(Block)、單句註釋、欄位名註釋,然後分別為eclipse、IDEA建立註釋模組等。
二、約定
下面就是一些常見的註釋示例:
1、版權註釋
版權註釋主要用來宣告公司的一些基本資訊等:
- /**
- * projectName: xxx
- * fileName: Tk.java
- * packageName: xxxx
- * date: 2017年12月18日下午12:28:39
- * copyright(c) 2017-2020 xxx公司
- */
2、類註釋(Class)
類註釋(Class)主要用來宣告該類用來做什麼,以及建立者、建立日期版本、包名等一些資訊:
- /**
- * @version: V1.0
- * @author: fendo
- * @className: user
- * @packageName: user
- * @description: 這是使用者類
- * @data: 2017-07-28 12:20
- **/
3、建構函式註釋(Constructor)
建構函式註釋(Constructor)主要用來宣告該類的建構函式、入參等資訊:
- **
- * @description: 建構函式
-
* @param: [sid, pid]
- */
4、方法註釋(Methods)
方法註釋(Methods)主要用來宣告該類的作用、入參、返回值、異常等資訊:
- /**
- * @author: fendo
- * @methodsName: addUser
- * @description: 新增一個使用者
- * @param: xxxx
- * @return: String
- * @throws:
- */
5、程式碼塊註釋(Block)
- /**
- * 例項化一個使用者
- * xxxxxxx
- */
- User user=new User();
6、單句註釋
- User user=new User(); //例項化一個使用者
7、欄位名註釋
- /**
- * 使用者名稱
- */
- public String name;
或者使用如下格式:
- /**使用者名稱**/
- public String name;
三、IDE模板
接下來就是分別在Eclipse和IDEA中實現上面的註釋,然後分別生成模板:
3.1、Eclipse程式碼註釋
在Eclipse中可以通過CodeTemplates進行設定,具體步驟如下: Window->Preference->Java->Code Style->Code Template
其中有兩類一類是Comments、主要是類中的一些通用模板:
1.檔案(Files)註釋標籤:
設定版權資訊:
- /**
- * projectName: ${project_name}
- * fileName: ${file_name}
- * packageName: ${package_name}
- * date: ${date}${time}
- * copyright(c) 2017-2020 xxx公司
- */
注意: 要打上勾!!
2.型別(Types)註釋標籤(類的註釋):
- /**
- * @title: ${file_name}
- * @package ${package_name}
- * @description: ${todo}
- * @author: fendo
- * @date: ${date} ${time}
- * @version: V1.0
- */
3.欄位(Fields)註釋標籤:
- /**
- * @Fields ${field} : ${todo}(用一句話描述這個變量表示什麼)
- */
4.建構函式(Constructors)標籤:
- /**
- * @title: ${enclosing_type}
- * @description: ${todo}(這裡用一句話描述這個方法的作用)
- * @param: ${tags}
- * @throws:
- */
5.方法(Methods)標籤:
- /**
- *@title: ${enclosing_method}
- *@description: ${todo}
- *@author: fendo
- *@date: ${date} ${time}
- *${tags}
- *@throws:
- */
6.覆蓋方法(Overriding Methods)標籤:
- /**
- * @title: ${enclosing_method}
- * @description: ${todo}
- * ${tags}
- * ${see_to_overridden}
- */
7.代表方法(Delegate Methods)標籤:
- /**
- * ${tags}
- * ${see_to_target}
- */
8.Getter方法標籤:
- /**
- * @title: ${enclosing_method}
- * @description: ${todo}
- * @return: ${field_type}
- */
9.Setter方法標籤:
- /**
- * @title: ${enclosing_method}
- * @description: ${todo}
- * @return: ${field_type}
- */
另一類是程式碼模板如下: