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) 內建的預設代碼格式對代碼進行格式化；

五、其他規範

       JSP 檔案命名
            採用完整的英文描述說明 JSP 所完成的功能，儘可能包括一個生動的動詞，第一個字母小寫，如： viewMessage.jsp 、editUser.jsp 等。

六、工程特有命名規範

        1、持久層
            1、 Hibernate 對應檔及實體
                與資料庫表名稱完全對應；
                如： Advertisement.hbm.xml 、 Advertisement.java
            2、資料訪問 DAO
                DAO 介面和實作類別名稱必須完全符合正常介面和實作類別的命名規則，且最後以 ”DAO” 結尾
                DAO 內的資料存取方法必須足夠抽象的描述出對資料庫的基本 CRUD 操作；
                如： ICrossAdDAO( 介面 ) 、 CrossAdDAO( 實作類別 )          
           3、各種操作資料庫的 HQL 設定檔
                HQL 檔案的個數原則上與系統的 Services 層的服務個數相等，且以服務名稱命名 HQL 檔案；
                如： resource.hbm.xml
        2、服務層
            1、服務介面和實現
                服務介面和實作類別必須完全符合正常介面和實作類別的命名規則；以工程定義的服務名為主體，並統一以 ”Serv” 結尾
                如： IResourceServ( 服務介面 ) 、 ResourceServ( 介面實作類別 )
            2、服務介面方法
                方法名是一個動詞，採用大小寫混合的方式，第一個單詞的首字母小寫，其後單詞的首字母大寫。方法名儘可能的描述出該方法的動作行為。
                傳回型別為 Boolean 值：用“ is ”或“ has ”來開頭
                得到某資料： get+ 資料描述名詞複數 + 資料類型；
                得到所有資料： get+All+ 資料描述名詞複數 + 資料類型；
                通過 XXX 得到 / 查詢某資料： get/query+ 資料描述名詞複數 + 資料類型 +By+ 條件；
                添加某資料： save/add+ 資料描述名詞 ()
                更新某資料： save/update+ 資料描述名詞；
                刪除某資料： delete/remove+ 資料描述名詞；
            3、業務對象
                業務名稱 +BO
            4、查詢參數對象
                凡是繼承 Abst***QuerySpec 的查詢參數類全部滿足以下規則：
                Query+ 所要查詢的資料描述名詞 +Spec
                作為參數傳入時，參數名必須為：所要查詢的資料描述名詞 +Spec
                如： QueryProgramSpec;
        3、MVC 層           
            1、Action 控制層
                Action 類名：功能模組名稱 +Action ；
                Actoin 方法名稱儘可能的描述出頁面遷移的去向
                如： LoginAction( 登入用 action) ， toWelcome( 轉向歡迎頁面的 action 方法 )
            2、資源檔
                系統全域資源檔： globalMessages_+ 字元編碼類型 +.properties
                功能模組內部的資源檔： package.properties
        4、Spring 設定檔
            1、Action 相關設定檔
                檔案目錄： WebRoot/WEB-INF/spring/action/ 功能模組名稱 +_ApplicationContext.xml
            2、Services 相關設定檔
                檔案目錄： WebRoot/WEB-INF/spring/services/Services_ApplicationContext.xml
            3、全域性設定檔
                檔案目錄： WebRoot/WEB-INF/spring/工程名+_ApplicationContext.xml
        5、JSP 檔案
            採用完整的英文描述說明 JSP 所完成的功能，儘可能包括一個生動的動詞，第一個字母小寫，如： viewMessage.jsp、editUser.jsp 等。