天天看點

阿裡Java編碼手冊實戰詳解-命名規範篇

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

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

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 的命名方式,是以,需要在

<resultMap> 設定從 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. 【推薦】 如果子產品、接口、類、方法使用了設計模式,在命名時需展現出具體模式。

說明: 将設計模式展現在名字中,有利于閱讀者快速了解架構設計理念。

2/44 Java 開發手冊

正例: public class OrderFactory;

public class LoginProxy;

public class ResourceObserver;

15. 【推薦】 接口類中的方法和屬性不要加任何修飾符号(public 也不要加),保持代碼的簡潔

性,并加上有效的 Javadoc 注釋。盡量不要在接口裡定義變量,如果一定要定義變量,肯定

是與接口方法相關,并且是整個應用的基礎常量。

正例: 接口方法簽名 void commit();

接口基礎常量 String COMPANY = "alibaba";

反例: 接口方法定義 public abstract void f();

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

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

1) 【強制】 對于 Service 和 DAO 類,基于 SOA 的理念,暴露出來的服務一定是接口,内部的實作類用

Impl 的字尾與接口差別。

正例: CacheServiceImpl 實作 CacheService 接口。

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

正例: AbstractTranslator 實作 Translatable 接口。

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

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

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

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。