解讀阿里巴巴《Java開發手冊》(1)編程規約-命名風格

編程規約-命名風格

1 【強制】代碼中的命名均不能以下劃線或美元符號開始,也不能以下劃線或美元符號結束。

反例:_name / __name / $name / name_ / name$ / name__

解析:
Java標識符可以使用數字、字母、下劃線、美元符號、人民幣符號組成,但是標識符首位不能是數字開頭

2 【強制】代碼中的命名嚴禁使用拼音與英文混合的方式,更不允許直接使用中文的方式。

說明:正確的英文拼寫和語法可以讓閱讀者易於理解,避免歧義。注意,純拼音命名方式更要避免採用。
正例:renminbi / alibaba / taobao / youku / hangzhou 等國際通用的名稱,可視同英文。
反例:DaZhePromotion [打折] / getPingfenByName() [評分] / int 某變量 = 3

3 【強制】類名使用 UpperCamelCase 風格,但以下情形例外:DO / BO / DTO / VO / AO / PO / UID 等。

正例:JavaServerlessPlatform / UserDO / XmlService / TcpUdpDeal / TaPromotion
反例:javaserverlessplatform / UserDo / XMLService / TCPUDPDeal / TAPromotion

4 【強制】方法名、參數名、成員變量、局部變量都統一使用 lowerCamelCase 風格,必須遵從駝峯形式。

正例: localValue / getHttpMessage() / inputUserId

5 【強制】常量命名全部大寫,單詞間用下劃線隔開,力求語義表達完整清楚,不要嫌名字長。

正例:MAX_STOCK_COUNT / CACHE_EXPIRED_TIME
反例:MAX_COUNT / EXPIRED_TIME

6 【強制】抽象類命名使用 Abstract 或 Base 開頭;異常類命名使用 Exception 結尾;測試類命名以它要測試的類的名稱開始,以 Test 結尾。

7 【強制】類型與中括號緊挨相連來表示數組。

正例:定義整形數組 int[] arrayDemo;
反例:在 main 參數中,使用 String args[]來定義。

8 【強制】POJO 類中布爾類型變量都不要加 is 前綴,否則部分框架解析會引起序列化錯誤。

說明:在本文 MySQL 規約中的建表約定第一條,表達是與否的值採用 is_xxx 的命名方式,所以,需要在設置從 is_xxx 到 xxx 的映射關係。

反例:定義爲基本數據類型 Boolean isDeleted 的屬性,它的方法也是 isDeleted(),
RPC 框架在反向解析的時候,“誤以爲”對應的屬性名稱是 deleted,導致屬性獲取不到,進而拋出異常。

9 【強制】包名統一使用小寫,點分隔符之間有且僅有一個自然語義的英語單詞。包名統一使用單數形式,但是類名如果有複數含義,類名可以使用複數形式。

正例:應用工具類包名爲 com.alibaba.ai.util、類名爲 MessageUtils(此規則參考 spring 的框架結構)

10 【強制】避免在子父類的成員變量之間、或者不同代碼塊的局部變量之間採用完全相同的命名,使可讀性降低。

說明:子類、父類成員變量名相同,即使是 public 類型的變量也是能夠通過編譯,而局部變量在同一方法內的不同代碼塊中同名也是合法的,但是要避免使用。對於非 setter/getter 的參數名稱也要避免與成員變量名稱相同。

反例:
public class ConfusingName {
        public int age;

        // 非 setter/getter 的參數名稱,不允許與本類成員變量同名
        public void getData(String alibaba) {
            if (condition) {
                final int money = 531;
                // ...
            }
            for (int i = 0; i < 10; i++) {
                // 在同一方法體中,不允許與其它代碼塊中的 money 命名相同
                final int money = 615;
                // ...
            }
        }
    }

    class Son extends ConfusingName {
        // 不允許與父類的成員變量名稱相同
        public int age;
    }

11 【強制】杜絕完全不規範的縮寫,避免望文不知義。

反例:AbstractClass“縮寫”命名成 AbsClass;condition“縮寫”命名成 condi,此類隨意縮寫嚴重
降低了代碼的可閱讀性。

12 【推薦】爲了達到代碼自解釋的目標,任何自定義編程元素在命名時,使用盡量完整的單詞組合來表達其意。

正例:在 JDK 中,表達原子更新的類名爲:AtomicReferenceFieldUpdater。
反例:int a 的隨意命名方式。

13 【推薦】在常量與變量的命名時,表示類型的名詞放在詞尾,以提升辨識度。

正例:startTime / workQueue / nameList / TERMINATED_THREAD_COUNT
反例:startedAt / QueueOfWork / listName / COUNT_TERMINATED_THREAD

14 【推薦】如果模塊、接口、類、方法使用了設計模式,在命名時需體現出具體模式。

說明:將設計模式體現在名字中,有利於閱讀者快速理解架構設計理念。

正例: 
public class OrderFactory;
public class LoginProxy;
public class ResourceObserver;

15 【推薦】接口類中的方法和屬性不要加任何修飾符號(public 也不要加),保持代碼的簡潔性,並加上有效的 Javadoc 註釋。儘量不要在接口裏定義變量,如果一定要定義變量,肯定是與接口方法相關,並且是整個應用的基礎常量。

說明:JDK8 中接口允許有默認實現,那麼這個 default 方法,是對所有實現類都有價值的默認實現。

正例:
接口方法簽名 void commit();
接口基礎常量 String COMPANY = "alibaba";
反例:
接口方法定義 public abstract void f();

解析:
接口中的方法被隱士指定爲public abstract,如果指定其他的修飾會報錯
接口中變量被隱士指定爲public abstract final,如果指定其他的修飾會報錯

16 接口和實現類的命名有兩套規則:

1)【強制】對於 Service 和 DAO 類,基於 SOA 的理念,暴露出來的服務一定是接口,內部的實現類用Impl 的後綴與接口區別。

正例:CacheServiceImpl 實現 CacheService 接口。

2)【推薦】如果是形容能力的接口名稱,取對應的形容詞爲接口名(通常是–able 的形容詞)。

正例:AbstractTranslator 實現 Translatable 接口。

17 【參考】枚舉類名帶上 Enum 後綴,枚舉成員名稱需要全大寫,單詞間用下劃線隔開。

說明:枚舉其實就是特殊的類,域成員均爲常量,且構造方法被默認強制是私有。

正例:枚舉名字爲 ProcessStatusEnum 的成員名稱:SUCCESS / UNKNOWN_REASON。

1.18 【參考】各層命名規約:

A) Service/DAO 層方法命名規約

1) 獲取單個對象的方法用 get 做前綴。
2) 獲取多個對象的方法用 list 做前綴,複數形式結尾如:listObjects。
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。
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章