Like Share Discussion Bookmark Smile

J.J. Huang   2020-04-28   Java   瀏覽次數:

《阿里Java開發手冊》 | 編程規約 - 命名風格

【強制】程式碼中的命名均不能以底線或美元符號開始,也不能以底線或美元符號結束。
反例:_name / __name / $name / name_ / name$ / name__


【強制】程式碼中的命名嚴禁使用拼音與英文混合的方式,更不允許直接使用中文的方式。
說明:正確的英文拼寫和語法可以讓閱讀者易於理解,避免歧義。注意,純拼音命名方式更要避免採用。
正例:ali / alibaba / taobao / cainiao/ aliyun/ youku / hangzhou 等國際通用的名稱,可視同英文。
反例:DaZhePromotion [打折] / getPingfenByName() [評分] / int 某變數 = 3


【強制】類名使用UpperCamelCase風格,但以下情形例外:DO/BO/DTO/VO/AO / PO / UID 等。
正例:ForceCode / UserDO / HtmlDTO / XmlService / TcpUdpDeal / TaPromotion
反例:forcecode / UserDo / HTMLDto / XMLService / TCPUDPDeal / TAPromotion


【強制】方法名、參數名、成員變數、局部變數都統一使用lowerCamelCase風格,必須遵從駝峰形式。
正例:localValue / getHttpMessage() / inputUserId


【強制】常數命名全部大寫,單詞間用底線隔開,力求語義表達完整清楚,不要嫌名字長。
正例:MAX_STOCK_COUNT / CACHE_EXPIRED_TIME
反例:MAX_COUNT / EXPIRED_TIME


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


【強制】類型與中括號緊挨相連來表示陣列。
正例:定義整形陣列 int[] arrayDemo;
反例:在 main 參數中,使用 String args[]來定義。


【強制】POJO類中布林類型變數都不要加is前綴,否則部分框架解析會引起序列化錯誤。
說明:在本文MySQL 規約中的建表約定第一條,表達是與否的值採用 is_xxx 的命名方式,所以,需要在設置從is_xxx 到 xxx 的映射關係。
反例:定義為基本資料類型Boolean isDeleted 的屬性,它的方法也是isDeleted(),RPC 框架在反向解析的時候,“誤以為”對應的屬性名稱是deleted,導致屬性獲取不到,進而拋出異常。


【強制】包名統一使用小寫,點分隔符之間有且僅有一個自然語義的英語單詞。包名統一使用單數形式,但是類名如果有復數含義,類名可以使用複數形式。
正例:應用工具類包名為 com.alibaba.ai.util、類名為 MessageUtils(此規則參考 spring 的框架結構)


【強制】避免在子父類的成員變數之間、或者不同程式碼塊的局部變數之間採用完全相同的命名,使可讀性降低。
說明:子類、父類成員變數名相同,即使是public 類型的變數也是能夠通過編譯,而局部變數在同一方法內的不同程式碼塊中同名也是合法的,但是要避免使用。對於非 setter/getter 的參數名稱也要避免與成員變數名稱相同。
反例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public class ConfusingName {
public int stock;
// 非 setter/getter 的參數名稱,不允許與本類成員變數同名
public void get(String alibaba) {
if (condition) {
final int money = 666;
// ...
}
for (int i = 0; i < 10; i++) {
// 在同一方法體中,不允許與其它程式碼塊中的 money 命名相同 final int money = 15978;
// ...
}
}
}
class Son extends ConfusingName {
// 不允許與父類的成員變數名稱相同 public int stock;
}

【強制】杜絕完全不規範的縮寫,避免望文不知義。
反例:AbstractClass“縮寫”命名成 AbsClass;condition“縮寫”命名成 condi,此類隨意縮寫嚴重 降低了程式碼的可閱讀性。


【推薦】為了達到程式碼自解釋的目標,任何自定義編程元素在命名時,使用盡量完整的單詞組合來表達其意。
正例:在 JDK 中,表達原子更新的類名為:AtomicReferenceFieldUpdater。
反例:常見的方法內變數為 int a;的定義方式。


【推薦】在常數與變數的命名時,表示類型的名詞放在詞尾,以提升辨識度。
正例:startTime / workQueue / nameList / TERMINATED_THREAD_COUNT
反例:startedAt / QueueOfWork / listName / COUNT_TERMINATED_THREAD


【推薦】如果模組、接口、類、方法使用了設計模式,在命名時需體現出具體模式。說明:將設計模式體現在名字中,有利於閱讀者快速理解架構設計理念。
正例:
public class OrderFactory;
public class LoginProxy;
public class ResourceObserver;


【推薦】接口類中的方法和屬性不要加任何修飾符號(public 也不要加),保持程式碼的簡潔性,並加上有效的Javadoc 註解。盡量不要在接口裡定義變數,如果一定要定義變數,肯定 是與接口方法相關,並且是整個應用的基礎常數。
正例:
接口方法簽名 void commit();
接口基礎常數 String COMPANY = “alibaba”;
反例:接口方法定義 public abstract void f();
說明:JDK8 中接口允許有預設實作,那麼這個 default 方法,是對所有實作類都有價值的預設實作。


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

  • 1.【強制】對於 Service 和 DAO 類,基於 SOA 的理念,暴露出來的服務一定是接口,內部的實作類用
    Impl 的後綴與接口區別。
    正例:CacheServiceImpl 實作 CacheService 接口。
  • 2.【推薦】如果是形容能力的接口名稱,取對應的形容詞為接口名(通常是–able 的形容詞)。
    正例:AbstractTranslator 實作 Translatable 接口。

【參考】枚舉類名帶上 Enum 後綴,枚舉成員名稱需要全大寫,單詞間用底線隔開。
說明:枚舉其實就是特殊的類,域成員均為常數,且構造方法被預設強制是私有。
正例:枚舉名字為 ProcessStatusEnum 的成員名稱:SUCCESS / UNKNOWN_REASON。


【參考】各層命名規約:

  • 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。

心得

看完這篇「命名風格」後,發現自己在命名「Service/DAO 層方法命名規約」的部分,自己並沒有命名的很好;例如取得多個對象的方法,並沒有用 list 當前綴,反而是在後綴加上,雖然沒有說這樣不對,但是放在前面似乎是比較利於閱讀。

還有布林類型變數都不要加is前綴,這點說明得非常清楚,自己所能想到的問題是在做序列化反序列化的時候,可能造成問題。

其他的命名規範基本上在平常就已經養成這樣的習慣了,只能說受益良多。嘿嘿。

結語

文章越看越多,技術越學越多,就會發現自己的不足;技術學到後面都會想要將基礎再重新在打得更加扎實。

以前在開發覺得理所當然的事情,例如:命名規則、命名規範,照著別人怎麼說就怎麼做的想法,並沒有好好去想為什麼要這樣設計和規範。
於是乎同事們推薦《阿里巴巴Java開發手冊》來做閱讀,書中提到種種規範《正確範例》、《錯誤範例》還有解釋定義說明;我相信在閱讀完這一系列後,一定會更加扎實且實在。

如對此書有興趣,建議去購買官方認證的書籍,給予官方支持。

註:如有侵權,通知即刪。


註:以上參考了
Alibaba-Java-Coding-Guidelines Github
Alibaba-Java-Coding-Guidelines English Version