java程式設計規範

最近經常看一些朋友寫的原始碼，總是感覺編碼規範問題還沒有成為大家的關注點，導致程式碼的通用可讀性相對比較差；

所以在此嘮叨幾句編碼規範（以struts2+spring2+hibernate3架構的專案為例），大家各取所需，歡迎拍磚！

一、規範存在的意義

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

    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 所完成的功能，儘可能包括一個生動的動詞，第一個字母小寫，v

來自 “ ITPUB部落格 ” ，連結：http://blog.itpub.net/21359667/viewspace-604378/，如需轉載，請註明出處，否則將追究法律責任。