阿里巴巴Java開發手冊:編程規約.命名風格

命名風格

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

反例:$name

/ name_ / name$ /name__

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

正例:alibaba / taobao / youku / hangzhou 等國際通用的名稱,可視同英文。

反例:DaZhePromotion [打折] / getPingfenByName() [評分] / int 某變量 = 3

說明:正確的英文拼寫和語法可以讓閱讀者易於理解,避免歧義。注意,即使純拼音命名方式也要避免採用。

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

正例:MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion

反例:macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion

說明:UpperCamelCase叫做"大駱駝拼寫法",又稱"帕斯卡拼寫法"(PascalCase),第一個詞的首字母,以及後面每個詞的首字母都大寫

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

正例: localValue / getHttpMessage() / inputUserId

說明:lowerCamelCase叫做"小駱駝拼寫法",第一個詞的首字母小寫,後面每個詞的首字母大寫。

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

正例:MAX_STOCK_COUNT

反例:MAX_COUNT

說明:Java中方法和變量的名稱長度限制爲2的16次方,一般來說要在清晰和長度中進行權衡。

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

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

正例:定義整形數組,int[] arrayDemo

反例:在 main 參數中,使用 String args[]來定義。

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

反例:定義布爾變量 private boolean isDeleted

說明:定義爲基本數據類型Boolean isDeleted的屬性,它的方法名是isDeleted(),RPC框架在反向解析的時候,“誤以爲”對應的屬性名稱是deleted,導致屬性獲取不到,進而拋出異常。這應該是阿里內部開發過程中獲得的教訓,通過遵循這個規範能夠從根源處減少此類bug的發生。

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

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

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

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

說明:這一點需要非常注意,我們在編碼的過程中可能會因爲變量太長而將名稱進行縮寫,很多時候自己能夠理解,卻降低了代碼的可讀性。不要嫌名字長,能夠完整清晰的表達出意思纔是更好的做法。

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

正例:在JDK中,表達原子更新的類名爲:AtomicReferenceFieldUpdater

反例:變量 int a 的隨意命名方式。

說明:命名時需要使名字能夠說明該元素的含義,提高代碼的可讀性,不要使用臨時的命名方式,比如list,temp等。刷算法刷多了容易出現這種情況。

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

正例:

public class OrderFactory;

public class LoginProxy;

public class ResourceObserver;

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

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

正例:接口方法簽名void commit(); 接口基礎常量String COMPANY = “alibaba”;

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

說明:接口中方法會被隱式指定爲public abstract,並且只能是public abstract,其他修飾符如protected,private會報錯。jdk8以後,接口允許用default修飾方法,需要有方法體,是對所有實現類都有價值的默認實現。jdk9允許定義私有方法。

接口中變量會被隱式指定爲public static final,並且只能是public,其他修飾符如protected,private會報錯,並且因爲是final變量,必須顯式初始化。

jdk7-9具體接口的變化

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

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

正例:CacheServiceImpl實現CacheService接口。

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

正例:AbstractTranslator實現 Translatable接口。

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

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

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

16. 【參考】各層命名規約:

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。

總結

這一部分主要講的就是開發中的一些命名規範和風格,可以看到儘量要做到統一風格,同時提高代碼的可讀性和自解釋性,希望做到望文知意,看到名稱就知道這個類是什麼類型,這個方法能做到什麼,這個變量代表什麼。

編碼規範是較爲主觀的,有些人喜歡換行,有些人喜歡空格,但在團隊開發中,需要做到硬性統一,便於團隊成員之間的協作。

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章