《阿里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