Java基礎學習總結（92）——Java編碼規範之排版、註釋及命名

爲使開發人員養成良好的開發習慣，編寫可讀性強、易維護的程序，結合以往資料，現整理Java編碼規範，將之做爲開發人員的參照依據。

1、排版

一、相對獨立的程序塊之間必須加空行

下列狀況應該使用一個空行：

• 兩個方法之間

• 方法內的局部變量和方法的第一條語句之間

• 塊註釋或單行註釋以前

• 一個方法內的兩個邏輯段之間

二、單行長度不超過120個字符，如超出則換行，且操做符應放在行首，新行要有相對縮進

三、多個參數之間，二元運算符左右，for語句表達式之間應用空格隔開

表達式之間用空格隔開

四、多個短語句不要寫在一行中，也就是說一行只寫一條語句

五、while、for、if、do、case、default、switch等語句獨佔一行，且while、for、do、if等語句的執行部分不管有多少句，都要用「{}」括起來

六、程序首行縮進4個空格數，不容許使用TAB縮進（使用空格可很好的適應不一樣操做系統的開發工具）

2、註釋

註釋應遵循的原則：

• 註釋的內容要清楚、明瞭，含義準確，防止註釋二義性。同時應儘可能避免在註釋中使用縮寫，特別是不經常使用縮寫。如須要寫，則進行必要的說明。

• 源程序有效註釋量必須在30％以上。註釋語言必須準確、易懂、簡潔。

一、類註釋以「/** */」的方式放在class 或者 interface 關鍵字以前，import 關鍵字以後

註釋概要部分應要簡明扼要，用簡短的語句描述清除類的主要用途。註釋可根據須要列出：做者、內容、功能、與其它類的關係等。

功能詳細描述部分說明該類或者接口的功能、做用、使用方法和注意事項，每次修改後增長做者和更新版本號和日期，@since 表示從那個版本開始就有這個類或者接口，以下圖：

類的註釋

二、方法的註釋，需列出方法的一句話功能簡述、功能詳細描述、輸入參數、輸出參數、返回值、異常等，以下圖所示：

方法的註釋

三、對代碼行的註釋：註釋應與其描述的代碼相近，對代碼的註釋應放在其上方，並與其上面的代碼用空行隔開，註釋與所描述內容進行一樣的縮排。

四、對代碼進行修改時，應同步修改相應的註釋，以保證註釋與代碼的一致性。再也不有用的註釋要刪除。

五、重寫父類方法時必須進行@Override聲明。

六、關鍵語句（條件分支、循環語句等）必須編寫註釋，精準的註釋位置可幫助維護人員更好的理解程序，其效果有時比看設計文檔要好的多。

七、方法內重要的單行代碼用「//」註釋，且註釋語句與上句代碼之間應空一行。

3、命名

一、包名採用域後綴倒置的加上自定義的包名，字母小寫，均以com.xxxx開頭(特殊狀況除外)

在部門內部應該規劃好包名的範圍，防止產生衝突。部門內部產品使用部門的名稱加上模塊名稱。產品線的產品使用產品的名稱加上模塊的名稱。除特殊緣由包結構都必須以com.xxxx開頭，若是由於OEM合做等關係，能夠不作要求。

二、類名和接口使用類意義完整的英文描述，英文單詞的首字母使用大寫、其他字母使用小寫的大小寫混合法，如：

OrderInformation, CustomerList, LogManager等

三、方法名使用意義完整的英文描述：第一個單詞的字母使用小寫、其他單詞首字母大寫其他字母小寫的大小寫混合法，如：

• public static boolean checkAuthorization(){……}

• public static String makeAuthorizationCode(){……}

四、相關方法中的存取屬性的方法採用setter 和 getter方法，動做方法採用動詞和動賓結構，如：

• get + 非布爾屬性名()：public String getType();

• is + 布爾屬性名()：public boolean isFinished();

• set + 屬性名()：public void setVisible(boolean);

• 動詞()：public void show();

• 動詞 + 賓語()：public void addKey(Listener);
  

五、屬性名使用完整的英文單詞，首單詞的字母小寫，其餘單詞首字母大寫其他字母小寫，如：

• private orderNumber;

• private smpSession;

• private customerName;

六、避免使用學術專業術語（魔法數字等）看成變量，用有意義的常量名來替代。

如涉及物理狀態或者含有物理意義的常量，不該直接使用數字或單個字母，必須用有意義的靜態常量代替，如：

定義常量代替

七、常量名用大寫英文描述，單詞間用下劃線分隔，且用 static final修飾，如：

• public static final int PAGE_SIZE = 100;

• public static final String DEFAULT_START_DATE = "2020-01-01";

八、數組採用「類型[] 數組名」的方式定義 ，而不用「類型 數組名[]」的方式定義，如：

• 可讀性差：public String getCustomers()[]{ ....}

• 可讀性強：public String[] getCustomers(){ ....}

九、如函數的名稱大於15 個字母，則可去掉單詞的元音字母或者以業內約定俗成的縮寫方式命名，如：

可將 getCustomerInformation() 改成 getCustomerInfo()

十、集合類的屬性命名時，應儘可能以其複數形式表意，如：

students, orderItems