一、編程規約
(一) 命名規約
1. 【強制】所有編程相關命名均不能以下划線或美元符號開始,也不能以下划線或美元符號結束。
反例: _name / __name / $Object / name_ / name$ / Object$
6. 【強制】抽象類命名使用Abstract或Base開頭;異常類命名使用Exception結尾;測試類命名以它要測試的類的名稱開始,以Test結尾。
8. 【強制】POJO類中的任何布爾類型的變量,都不要加is,否則部分框架解析會引起序列化錯誤。
反例:定義為基本數據類型boolean isSuccess;的屬性,它的方法也是isSuccess(),RPC框架在反向解析的時候,“以為”對應的屬性名稱是success,導致屬性獲取不到,進而拋出異常
9. 【強制】包名統一使用小寫,點分隔符之間有且僅有一個自然語義的英語單詞。包名統一使用單數形式,但是類名如果有復數含義,類名可以使用復數形式。
正例: 應用工具類包名為com.alibaba.mpp.util、類名為MessageUtils(此規則參考spring的框架結構)
11.【推薦】如果使用到了設計模式,建議在類名中體現出具體模式。 說明:將設計模式體現在名字中,有利於閱讀者快速理解架構設計思想。
正例:public class OrderFactory; public class LoginProxy; public class ResourceObserver;
12.【推薦】接口類中的方法和屬性不要加任何修飾符號(public 也不要加),保持代碼的簡潔性,並加上有效的javadoc注釋。盡量不要在接口里定義變量,如果一定要定義變量,肯定是與接口方法相關,並且是整個應用的基礎常量。
正例:接口方法簽名:void f(); 接口基礎常量表示:String COMPANY = "alibaba"; 反例:接口方法定義:public abstract void f(); 說明:JDK8中接口允許有默認實現,那么這個default方法,是對所有實現類都有價值的默認實現。
13.接口和實現類的命名有兩套規則:
1)【強制】對於Service和DAO類,基於SOA的理念,暴露出來的服務一定是接口,內部的實現類用Impl的后綴與接口區別。 正例:CacheServiceImpl實現CacheService接口。
2)【推薦】 如果是形容能力的接口名稱,取對應的形容詞做接口名(通常是–able的形式)。 正例:AbstractTranslator實現 Translatable。
14.【參考】枚舉類名建議帶上Enum后綴,枚舉成員名稱需要全大寫,單詞間用下划線隔開。 說明:枚舉其實就是特殊的常量類,且構造方法被默認強制是私有。 正例:枚舉名字:DealStatusEnum;成員名稱:SUCCESS / UNKOWN_REASON
15.【參考】各層命名規約:
A) Service/DAO層方法命名規約
1) 獲取單個對象的方法用get做前綴。
2) 獲取多個對象的方法用list做前綴。
3) 獲取統計值的方法用count做前綴。
4) 插入的方法用save(推薦)或insert做前綴。
5) 刪除的方法用remove(推薦)或delete做前綴。
6) 修改的方法用update做前綴。
B) 領域模型命名規約
1) 數據對象:xxxDO,xxx即為數據表名。
2) 數據傳輸對象:xxxDTO,xxx為業務領域相關的名稱。
3) 展示對象:xxxVO,xxx一般為網頁名稱。
4) POJO是DO/DTO/BO/VO的統稱,禁止命名成xxxPOJO。
(二) 常量定義
2. 【強制】long或者Long初始賦值時,必須使用大寫的L,不能是小寫的l,小寫容易跟數字1混淆,造成誤解。
說明:Long a = 2l; 寫的是數字的21,還是Long型的2?
3. 【推薦】不要使用一個常量類維護所有常量,應該按常量功能進行歸類,分開維護。如:緩存相關的常量放在類:CacheConsts下;系統配置相關的常量放在類:ConfigConsts下。 說明:大而全的常量類,非得ctrl+f才定位到修改的常量,不利於理解,也不利於維護。
4. 【推薦】常量的復用層次有五層:跨應用共享常量、應用內共享常量、子工程內共享常量、包內共享常量、類內共享常量。
1) 跨應用共享常量:放置在二方庫中,通常是client.jar中的const目錄下。
2) 應用內共享常量:放置在一方庫的modules中的const目錄下。 反例:易懂變量也要統一定義成應用內共享常量,兩位攻城師在兩個類中分別定義了表示“是”的變量: 類A中:public static final String YES = "yes"; 類B中:public static final String YES = "y"; A.YES.equals(B.YES),預期是true,但實際返回為false,導致產生線上問題。
3) 子工程內部共享常量:即在當前子工程的const目錄下。
4) 包內共享常量:即在當前包下單獨的const目錄下。
5) 類內共享常量:直接在類內部private static final定義。
5. 【推薦】如果變量值僅在一個范圍內變化用Enum類。如果還帶有名稱之外的延伸屬性,必須使用Enum類,下面正例中的數字就是延伸信息,表示星期幾。
正例:public Enum{ MONDAY(1), TUESDAY(2), WEDNESDAY(3), THURSDAY(4), FRIDAY(5), SATURDAY(6), SUNDAY(7);}