編程規約(上) -- 阿里巴巴Java開發手冊

沒有標註 "推薦" 等字樣的, 爲強制標準.

加粗的爲不熟悉的.

一.命名風格

1-1.代碼中的命名均不能如下劃線或美圓符號開始或結束

String _name, $name; // not

1-2.嚴禁使用拼音和英文混合,不能使用中文, 國際通用的名稱,可視同英文

String getPingfenByName; //not

1-3.類名使用駝峯命名,首字母大寫,DO / BO / DTO / VO / AO / PO /UID 等除外

1-4.方法名,參數名,變量都採用 lowerCanelCase 風格

1-5.常量命名所有大寫,單詞間用下劃線隔開.不要嫌名字長,語意表達完整

String MAX_STOCK_COUNT;

1-6.抽象類名使用 Abstract 或 Base 開頭，異常類名使用 Exception 結尾，測試類名以它要測試的類名開始 ，Test 結尾。

1-7.表示數組, 類型[] 變量名;

int[] arrayDemo;  //yes
int arrayDemo1[]; //not

1-8.POJO類中布爾類型的變量,都不要加 is 前綴,不然部分框架解析會引發序列化錯誤.

Boolean isDelete; //not

1-9.包名統一使用小寫，點分隔符之間有且僅有一個天然語義的單詞；包名統一使用單數形式,類名可使用複數形式。

1-10.杜毫不規範的縮寫致使望文不知義 Condition --> condi

 

推薦：

1-11.任何自定義編程元素在命名時儘可能使用完整的單詞組合來表達， 反例 int a；

1-12.若是模塊，接口，類，方法使用了設計模式，在命名時需體現出具體模式。

　　例如：OrderFactory，LoginProxy， ResourceObserver

1-13.接口類中的方法和屬性不要加任何的修飾符號(public也不加)，並加上有效的JavaDoc註釋。

　　儘可能不要在接口裏定義變量，若是要，確定是與接口方法相關,，而且是整個應用的基礎常量。

　　JDK8 default方法，是對全部實現類都有價值的默認實現

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

　　1) 對於 Service 和  DAO類, 基於 SOA的理念,暴露出來的服務必定是接口,內部的實現類用 Impl 後綴區分

　　2) (推薦) 若是是形容能力的接口名稱,取對應的形容詞爲接口名( -able 形式)

 

參考：

1-15.枚舉類建議帶上Enum後綴, 枚舉成員名稱須要全大寫,單詞間用下劃線隔開。

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

　　例如：枚舉名爲 ProcessStatusEnum ， 成員名 SUCCESS / UNKNOWN_REASON

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

 

二.常量定義

2-1.不容許使用任何魔法值(即未經預先定義的常量) 直接出如今代碼中.

　　例如: int priceTable[] = new int[16]; //ERROR：這個16究竟有何含義呢?

2-2.在使用Long或者long賦值時, 數值後使用大寫的L

推薦:

2-3.不要使用一個常量類維護全部常量,要按照常量功能進行歸類.

2-4.常量的複用層次有五層: 跨應用共享,應用內共享,子工程內共享,包內共享,類內共享

　　1) 跨應用: 放置在二方庫中,一般是 client.jar 中的 constant 目錄下
　　2) 應用內: 放置在一方庫中,一般是子模塊中的 constant 目錄下
　　3) 子工程內: 即在當前子工程的 constant 目錄下
　　4) 包內: 即在當前包下單獨的constant目錄下
　　5) 類內: 直接在類內部 private static final 定義.

2-5.若是變量值僅在一個固定範圍內變化,用enum類型來定義

 

三.代碼格式

3-1.大括號的使用約定,大括號內爲空,寫成 { } 便可. 非空寫成如下格式

public void method() { //1.左大括號前不換行,後換行. 2.左大括號前須要空格
 }//右大括號前換行,後還有else則不換行,表示停止的右大括號必須換行

3-2.小括號和字符之間不出現空格

if ( a==b ) //not

3-3.if /for /while /switch /do 等保留字與括號之間都必須加空格

3-4.任何二目,三目運算符的左右兩邊都須要一個空格.

3-5.採用4個空格縮進,禁止使用tab字符

說明：若是使用 tab 縮進，必須設置 1 個 tab 爲 4 個空格。IDEA 設置 tab 爲 4 個空格時，
　　　請勿勾選 Use tab character；而在 eclipse 中，必須勾選 insert spaces for tabs。

//正例 (1-5)
public static void main(String[] args) { // 縮進 4 個空格 
    String say = "hello"; // 運算符的左右必須有一個空格 
    int flag = 0; // 關鍵詞 if 與括號之間必須有一個空格，括號內的 f 與左括號,0 與右括號不須要空格 
    if (flag == 0) { System.out.println(say); } // 左大括號前加空格且不換行；左大括號後換行
    if (flag == 1) { System.out.println("world"); // 右大括號前換行，右大括號後有 else，不用換行 
    } else { System.out.println("ok"); // 在右大括號後直接結束，則必須換行 
 } }

 

3-6.註釋的雙斜線與註釋內容之間有且僅有一個空格

3-7.單行字符數限制不超過120個, 超出換行, 換行原則 :

　　1) 第二行相對第一行縮進4空格,第三行開始再也不縮進
　　2) 運算符與下文一塊兒換行
　　3) 方法調用點符號與下文一塊兒換行
　　4) 方法調用中的參數須要換行時,在逗號後進行
　　5) 在括號前不要換行,逗號前不要換行

3-8.方法參數在定義和傳入時,多個參數逗號後必須加空格

3-9.IDE的 test file encoding 設置爲 UTF-8; IDE 中文件的換行符使用 Unix格式, 不要使用windows格式.

 

推薦 :

3-10.單個方法的總行數不超過80行,包括註釋,大括號,空行等.

代碼邏輯分清紅花和綠葉,個性和共性,
綠葉邏輯單獨出來成爲額外方法,使主幹代碼更加清晰.
共性邏輯抽取成共性方法,便於維護和複用.

3-12.不一樣邏輯,不一樣語義,不一樣業務的代碼之間插入一個空行分隔開來以提高可讀性. 沒必要插入多個空行.

 

四.OOP規約

4-1.不要使用一個類的對象引用訪問此類的靜態變量或靜態方法, 無畏增長編譯器解析成本.

4-2.全部的覆寫方法,必須加@Override 註解

4-3.相同參數類型,業務含義,纔可使用可變參數,避免使用Object. (提倡儘可能不使用可變參數編程)

4-4.外部正在調用或者二方庫依賴的接口, 不容許修改方法簽名.
　  接口過期必須加 @Deprecated 註解,並清晰的說明採用的新接口或者新服務是什麼

4-5.不能使用過期的類或方法.

4-6.equals方法,應使用常量或肯定有值的對象來調用. 推薦使用 java.util.Objects#equals (JDK7引入的工具類)

4-7.全部的相同類型的包裝類對象之間值的比較,所有用equals方法比較. 包裝類:Integer等

4-8.關於基本數據類型與包裝數據類型的使用標準以下:
　　1) 全部的POJO類屬性必須使用包裝數據類型
　　2) RPC方法的返回值和參數必須使用包裝數據類型
　　3) (推薦) 全部的局部變量使用基本數據類型

4-9.定義DO/DTO/VO 等POJO類時, 不要設定任何屬性默認值

4-10.序列化類新增屬性時,請不要修改 serialVersionUID 字段,避免反序列失敗.

4-11.構造方法裏面禁止加入任何業務邏輯, 若是有初始化邏輯,請放在 init 方法中.

4-12.POJO類必須寫 toString 方法.若是繼承了另外一個POJO ,注意在前面加一下 super.toString

4-13.禁止在POJO類中,同時存在對應屬性的 isXxx() 和 getXxx() 方法.

說明:框架在調用屬性Xxx的提取方法時,不肯定哪一個方法被優先調用到

 

推薦:

4-14.使用索引訪問用String split 方法獲得的數組時,需作最後一個分隔符後有無內容的檢查.　　　　

String str = "a,b,c,,"; String[] ary = str.split(","); System.out.println(ary.length); //3

4-15.當一個類有多個構造方法,或者多個同名方法,這些方法應該按順序放置在一塊兒,便於閱讀.優先於16條規則.

4-16.類內方法定義的順序依次是: 公有方法或保護方法 >私有方法 >getter/setter 方法.

4-17.setter方法中,參數名稱與類成員變量名稱一致,不要在方法中增長業務邏輯,增長排查問題的難度.

4-18.循環體內,字符串的鏈接方式,使用StringBuilder 的 append 方法進行擴展.

4-19.final 能夠聲明類,成員變量,方法,以及本地變量.
　　1) 不容許被繼承的類
　　2) 不容許修改引用的域對象
　　3) 不容許被重寫的方法,例如 setter 方法
　　4) 不容許運行過程當中從新賦值的局部變量
　　5) 避免上下文重複使用一個變量,使用final描述能夠強制從新定義一個變量,方便更好的進行重構.  ??

4-20.慎用Object的clone方法來拷貝對象(淺拷貝),若要實現深拷貝須要重寫clone方法實現域對象的深度遍歷式拷貝

4-21.類成員與方法訪問控制從嚴 :
　　1) 若是不容許直接經過new來建立對象, 構造方法必須私有
　　2) 工具類不容許有public 或 default構造方法
　　3) 類中非static成員變量而且與子類共享,必須是protected
　　4) 類中非static成員變量而且僅在本類使用,必須是private
　　5) 類中static成員變若是僅在本類使用,必須是private
　　6) 如果static成員變量,考慮是否爲final
　　7) 類成員方法只供內部調用,必須是private
　　8) 類成員方法只對繼承類公開,那麼限制爲protected

說明: 任何類、方法、參數、變量，嚴控訪問範圍。過於寬泛的訪問範圍，不利於模塊解耦。思考：若是是一個 private 的方法，想刪除就刪除，但是一個 public 的 service 成員方法或 成員變量，刪除一下，不得手心冒點汗嗎？