Java 編程規範

標籤：

一、   編碼規範的意義

   應用編碼規範對於軟體本身和軟體開發人員而言尤為重要，有以下幾個原因：

1）好的編碼規範可以儘可能的減少一個軟體的維護成本 , 並且幾乎沒有任何一個軟體，在其整個生命週期中，均由最初的開發人員來維護；

2）好的編碼規範可以改善軟體的可讀性，可以讓開發人員儘快而徹底地理解新的代碼；

3）好的編碼規範可以最大限度的提高團隊開發的合作效率；

4）長期的規範性編碼還可以讓開發人員養成好的編碼習慣，甚至鍛鍊出更加嚴謹的思維；

二、具體命名規範

1、標識符的意義

1）盡量使用完整的英文描述符

2）採用適用於相關領域的術語
3）採用大小寫混合使名字可讀
4）盡量少用縮寫，但如果用了，必須符合整個工程中的統一定義
5）避免使用長的名字（小於 15個字母為正常選擇）
6）避免使用類似的名字，或者僅僅是大小寫不同的名字
7）避免使用底線（除靜態常量等）
2、標識符類型說明

 

1）包（Package ）的命名
            Package 的名字應該採用完整的英文描述符，都是由一個小寫單片語成。並且包名的首碼總是一個頂級網域名稱，通常是 com、edu、gov、mil、net、org等；
            如： com.yjhmily.test

 

2）類（ Class）的命名
            類名應該是個一名詞，採用大小寫混合的方式，每個單詞的首字母大寫。盡量保證類名簡潔而富於描述。使用完整單詞，避免縮寫詞 (除非工程內有統一縮寫規範或該縮寫詞被更廣泛使用，像 URL ， HTML)
        如： FileDescription

 

3）介面（ Interface）的命名
            基本與 Class的命名規範類似。在滿足 Classd 命名規則的基礎之上，保證開頭第一個字母為 ”I”，便於與普通的 Class區別開。其實作類別名稱取介面名的第二個字母到最後，且滿足類名的命名規範；
        如： IMenuEngine

 

4）枚舉（ Enum）的命名
            基本與 Class的命名規範類似。在滿足 Classd 命名規則的基礎之上，保證開頭第一個字母為 ”E”，便於與普通的 Class區別開。
        如： EUserRole

 

5）異常（ Exception）的命名
            異常（ Exception）通常採用字母 e 表示異常，對於自訂的異常類，其尾碼必須為 Exception
        如： BusinessException

 

6）方法（ Method ）的命名
            方法名是一個動詞，採用大小寫混合的方式，第一個單詞的首字母小寫，其後單詞的首字母大寫。方法名儘可能的描述出該方法的動作行為。傳回型別為 Boolean值的方法一般由“ is ”或“ has ”來開頭
        如： getCurrentUser()、 addUser() 、 hasAuthority()

 

7）參數（ Param）的命名
            第一個單詞的首字母小寫，其後單詞的首字母大寫。參數量名不允許以底線或貨幣符號開頭，雖然這在文法上是允許的。參數名應簡短且富於描述。
        如： public UserContext getLoginUser(String loginName);

 

8）常量欄位（ Constants）的命名
           靜態常量欄位（ static final ）全部採用大寫字母，單詞之間用底線分隔；
        如： public static final Long FEEDBACK;
               public static Long USER_STATUS;

 

三、注釋規範

1、注釋的意義

            1）注釋應該增加代碼的清晰度
            2）保持注釋的簡潔
            3）在寫代碼之前或同時寫注釋
            4）注釋出為什麼做了一些事，而不僅僅是做了什麼

 

2、 注釋哪些部分

 

            1）Java 檔案：必須寫明著作權資訊以及該檔案的建立時間和作者；
            2）類：類的目的、即類所完成的功能，以及該類建立的時間和作者名稱；多人一次編輯或修改同一個類時，應在作者名稱處出現多人的名稱；
            3）介面：在滿足類注釋的基礎之上，介面注釋應該包含設定介面的目的、它應如何被使用以及如何不被使用。在介面注釋清楚的前提下對應的實作類別可以不加註釋；
            4）方法注釋：對於設定 (Set方法 ) 與擷取 (Get方法 ) 成員的方法，在成員變數已有說明的情況下，可以不加註釋；普通成員方法要求說明完成什麼功能，參數含義是什麼且傳回值什麼；另外方法的建立時間必須注釋清楚，為將來的維護和閱讀提供寶貴線索；
            5）方法內部注釋：控制結構，代碼做了些什麼以及為什麼這樣做，處理順序等，特別是複雜的邏輯處理部分，要儘可能的給出詳細的注釋；
            6）參數：參數含義、及其它任何約束或前提條件；
            7）屬性：欄位描述；
            8）局部 (中間 ) 變數：無特別意義的情況下不加註釋；
 3、注釋格式
           遵循工程規定的統一注釋格式，一般情況下會以 codetemplates.xml格式的檔案匯入 IDE(Eclipse)或者用Eclipse預設的；

 

四、代碼格式規範
    遵循工程規定的統一代碼格式，一般情況下直接使用 IDE(Eclipse) 內建的預設代碼格式對代碼進行格式化；

1、單行(single-line)--短注釋：//……   
     單獨行注釋：在代碼中單起一行注釋， 注釋前最好有一行空行，並與其後的代碼具有一樣的縮排層級。如果單行無法完成，則應採用塊注釋。
注釋格式：/* 注釋內容 */
行頭注釋：在程式碼的開頭進行注釋。主要為了使該行代碼失去意義。
注釋格式：// 注釋內容

行章節附註釋：尾端(trailing)--極短的注釋，在程式碼的行尾進行注釋。一般與程式碼後空8（至少4）個格，所有注釋必須對齊。
注釋格式：代碼 + 8（至少4）個空格 + // 注釋內容

2、塊(block)--塊注釋：/*……*/
  注釋若干行，通常用於提供檔案、方法、資料結構等的意義與用途的說明，或者演算法的描述。一般位於一個檔案或者一個方法的前面，起到引導的作用，也可以根據需要放在合適的位置。這種域注釋不會出現在HTML報告中。注釋格式通常寫成：
/*
* 注釋內容
*/

 

3、文檔注釋：/**……*/

 

注釋若干行，並寫入javadoc文檔。每個文檔注釋都會被置於注釋定界符 /**......*/之中，注釋文檔將用來產生HTML格式的代碼報告，所以注釋文檔必須書寫在類、域、建構函式、方法，以及欄位(field)定義之前。注釋文檔由兩部分組成——描述、塊標記。注釋文檔的格式如下：

/**

* 注釋內容
*/

 

Java 編程規範