java代碼註釋規範

java代碼註釋規範

1、規範存在的意義

    應用編碼規範對於軟件自己和軟件開發人員而言尤其重要，有如下幾個緣由：

    一、好的編碼規範能夠儘量的減小一個軟件的維護成本 , 而且幾乎沒有任何一個軟件，在其整個生命週期中，均由最初的開發人員來維護；

    二、好的編碼規範能夠改善軟件的可讀性，可讓開發人員儘快而完全地理解新的代碼；

    三、好的編碼規範能夠最大限度的提升團隊開發的合做效率；

    四、長期的規範性編碼還可讓開發人員養成好的編碼習慣，甚至鍛煉出更加嚴謹的思惟；

2、命名規範

     一、通常概念

        一、儘可能使用完整的英文描述符

        二、採用適用於相關領域的術語

        三、採用大小寫混合使名字可讀

        四、儘可能少用縮寫，但若是用了，必須符合整個工程中的統必定義
       
        五、避免使用長的名字（小於 15 個字母爲正常選擇）

        六、避免使用相似的名字，或者僅僅是大小寫不一樣的名字

        七、避免使用下劃線（除靜態常量等）

      二、標識符類型說明

        一、包（ Package ）的命名
            Package 的名字應該採用完整的英文描述符，都是由一個小寫單詞組成。而且包名的前綴老是一個頂級域名，
            一般是 com、edu、gov、mil、net、org 等；
            如： com.yjhmily.test

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

        三、接口（ Interface ）的命名
            基本與 Class 的命名規範相似。在知足 Classd 命名規則的基礎之上，保證開頭第一個字母爲 」I」，
            便於與普通的 Class區別開。其實現類名稱取接口名的第二個字母到最後，且知足類名的命名規範；
        如： IMenuEngine

        四、枚舉（ Enum ）的命名
            基本與 Class 的命名規範相似。在知足 Classd 命名規則的基礎之上，保證開頭第一個字母爲 」E」 ，
            便於與普通的 Class區別開。
        如： EUserRole

        五、異常（ Exception ）的命名
            異常（ Exception ） 一般採用字母 e 表示異常，對於自定義的異常類，其後綴必須爲 Exception
        如： BusinessException

        六、方法（ Method ）的命名
            方法名是一個動詞，採用大小寫混合的方式，第一個單詞的首字母小寫，其後單詞的首字母大寫。
            方法名儘量的描述出該方法的動做行爲。返回類型爲 Boolean 值的方法通常由「 is 」或「 has 」來開頭
        如： getCurrentUser() 、 addUser() 、 hasAuthority()

        七、參數（ Param ）的命名
            第一個單詞的首字母小寫，其後單詞的首字母大寫。參數量名不容許如下劃線或美圓符號開頭，
            雖然這在語法上是容許的。參數名應簡短且富於描述。
        如： public UserContext getLoginUser(String loginName);
       
        八、常量字段 （ Constants ）的命名
            靜態常量字段（ static final ） 所有采用大寫字母，單詞之間用下劃線分隔；
        如： public static final Long FEEDBACK;
        public static Long USER_STATUS;

  3、註釋規範

        一個很好的可遵循的有關注釋的經驗法則是：

            問問你本身，你若是從未見過這段代碼，要在合理的時間內有效地明白這段代碼，你須要一些什麼信息？？？

         一、通常概念

            一、註釋應該增長代碼的清晰度

            二、保持註釋的簡潔

            三、在寫代碼以前或同時寫註釋

            四、註釋出爲何作了一些事，而不只僅是作了什麼

         二、註釋哪些部分

            一、Java 文件：必須寫明版權信息以及該文件的建立時間和做者；

            二、類：類的目的、即類所完成的功能，以及該類建立的時間和做者名稱；多人一次編輯或修改同一個類時，
                應在做者名稱處出現多人的名稱；

            三、接口： 在知足類註釋的基礎之上，接口註釋應該包含設置接口的目的、它應如何被使用以及如何不被使用。
                在接口註釋清楚的前提下對應的實現類能夠不加註釋；

            四、方法註釋： 對於設置 (Set 方法 ) 與獲取 (Get 方法 ) 成員的方法，在成員變量已有說明的狀況下，
                能夠不加註釋；普通成員方法要求說明完成什麼功能，參數含義是什麼且返回值什麼；另外方法的建立
                時間必須註釋清楚，爲未來的維護和閱讀提供寶貴線索；

            五、方法內部註釋： 控制結構，代碼作了些什麼以及爲何這樣作，處理順序等，特別是複雜的邏輯處理部分，
                要儘量的給出詳細的註釋；

            六、參數： 參數含義、及其它任何約束或前提條件；

            七、屬性： 字段描述；

            八、局部 ( 中間 ) 變量： 無特別意義的狀況下不加註釋；

         三、註釋格式

            遵循工程規定的統一註釋格式，通常狀況下會以 codetemplates.xml 格式的文件導入 IDE(Eclipse)
            或者用Eclipse默認的；

4、代碼格式規範

        遵循工程規定的統一代碼格式，通常狀況下直接使用 IDE(Eclipse) 自帶的默認代碼格式對代碼進行格式化；

一、單行(single-line)--短註釋：//……   
單獨行註釋：在代碼中單起一行註釋， 註釋前最好有一行空行，並與其後的代碼具備同樣的縮進層級。若是單行沒法完成，則應採用塊註釋。
註釋格式：
行頭註釋：在代碼行的開頭進行註釋。主要爲了使該行代碼失去意義。
註釋格式：// 註釋內容
行尾註釋：尾端(trailing)--極短的註釋，在代碼行的行尾進行註釋。通常與代碼行後空8（至少4）個格，全部註釋必須對齊。
註釋格式：代碼 + 8（至少4）個空格 + // 註釋內容
二、塊(block)--塊註釋：
註釋若干行，一般用於提供文件、方法、數據結構等的意義與用途的說明，或者算法的描述。通常位於一個文件或者一個方法的前面，起到引導的做用，也能夠根據須要放在合適的位置。這種域註釋不會出如今HTML報告中。註釋格式一般寫成：

三、文檔註釋：
註釋若干行，並寫入javadoc文檔。每一個文檔註釋都會被置於註釋定界符
之中，註釋文檔將用來生成HTML格式的代碼報告，因此註釋文
檔必須書寫在類、域、構造函數、方法，以及字段(field)定義以前。註釋文檔由兩部分組成——描述、塊標記。註釋文檔的格式以下：

public void doGet (HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
    doPost(request, response);
}
前兩行爲描述，描述完畢後，由@符號起頭爲塊標記註釋。更多有關文檔注
釋和javadoc的詳細資料，參見javadoc的主頁：  http://java.sun.com/javadoc/index.html
四、javadoc註釋標籤語法
@author    對類的說明 標明開發該類模塊的做者
@version   對類的說明 標明該類模塊的版本
@see      對類、屬性、方法的說明 參考轉向，也就是相關主題
@param    對方法的說明 對方法中某參數的說明
@return    對方法的說明 對方法返回值的說明
@exception  對方法的說明 對方法可能拋出的異常進行說明
6、JAVA註釋具體實現
一、源文件註釋
源文件註釋採用 ，在每一個源文件的頭部要有必要的註釋信息，包括：文件名；文件編號；版本號；做者；建立時間；文件描述包括本文件歷史修改記錄等。中文註釋模版：

二、類（模塊）註釋：
類（模塊）註釋採用 ，在每一個類（模塊）的頭部要有必要的註釋信息，包括：工程名；類（模塊）編號；命名空間；類能夠運行的JDK版本；版本號；做者；建立時間；類（模塊）功能描述（如功能、主要算法、內部各部分之間的關係、該類與其類的關係等，必要時還要有一些如特別的軟硬件要求等說明）；主要函數或過程清單及本類（模塊）歷史修改記錄等。
英文註釋模版：

若是模塊只進行部分少許代碼的修改時，則每次修改須添加如下注釋：
//Rewriter
//Rewrite Date：<修改日期:格式YYYY-MM-DD> Start1：

//End1：
將原代碼內容註釋掉，而後添加新代碼使用如下注釋：
//Added by
//Add date：<添加日期，格式：YYYY-MM-DD> Start2：
//End2：
若是模塊輸入輸出參數或功能結構有較大修改，則每次修改必須添加如下
註釋：
//Log ID：
//Depiction：<對此修改的描述>
//Writer：修改者中文名
//Rewrite Date：<模塊修改日期，格式：YYYY-MM-DD>
二、接口註釋：
接口註釋採用 ，在知足類註釋的基礎之上，接口註釋應該包含描述接口的目的、它應如何被使用以及如何不被使用，塊標記部分必須註明做者和版本。在接口註釋清楚的前提下對應的實現類能夠不加註釋。
三、構造函數註釋：
構造函數註釋採用 ，描述部分註明構造函數的做用，不必定有塊標記部分。
註釋模版一：

註釋模版二：

四、函數註釋：
函數註釋採用 ，在每一個函數或者過程的前面要有必要的註釋信息，包括：函數或過程名稱；功能描述；輸入、輸出及返回值說明；調用關係及被調用關係說明等。函數註釋裏面能夠不出現版本號（@version）。
註釋模版一：

註釋模版二：

五、方法註釋：
方法註釋採用 ，對於設置 (Set 方法 ) 與獲取 (Get 方法 ) 成員的方法，在成員變量已有說明的狀況下，能夠不加註釋；普通成員方法要求說明完成什麼功能，參數含義是什麼且返回值什麼；另外方法的建立時間必須註釋清楚，爲未來的維護和閱讀提供寶貴線索。
六、方法內部註釋：
控制結構，代碼作了些什麼以及爲何這樣作，處理順序等，特別是複雜的邏輯處理部分，要儘量的給出詳細的註釋。
七、 全局變量註釋：
要有較詳細的註釋，包括對其功能、取值範圍、哪些函數或者過程存取以及存取時注意事項等的說明。
八、局部（中間）變量註釋：
主要變量必須有註釋，無特別意義的狀況下能夠不加註釋。
九、實參/參數註釋：
參數含義、及其它任何約束或前提條件。
十、字段/屬性註釋： 字段描述，屬性說明。
十一、常量：常量一般具備必定的實際意義，要定義相應說明。

 －－－－－－－－－－－－－華麗的分割線－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－

myeclipse的註釋相關

1.對java文件的自動註釋

Window->Preference－＞Java -> Code Style -> Code Templates

files:新建文件時的註釋

Types：類的注視

Field：變量的註釋

Constructors:構造函數的註釋

methods：通常方法的註釋

能夠在裏edit一些固定的格式或變量 其中user默認取操做系統的名稱，能夠寫死。 日期格式俺想知道怎麼改爲yyyy-mm-dd

2.對JSP文件的註釋

Window->Preference-myeclipse-editors-JSP-JSP TEMPLATES

 3.在java中用的一些快捷 例：sysout

Window->Preference-java-editor-templates

能夠本身寫一些參數~例如 user ---zhongjb

5、其餘規範

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

6、工程特有命名規範

          一、持久層

            一、 Hibernate 映射文件及實體
                與數據庫表名稱徹底對應；
                如： Advertisement.hbm.xml 、 Advertisement.java

            二、數據訪問 DAO
                DAO 接口和實現類名稱必須徹底符合正常接口和實現類的命名規則，且最後以 」DAO」 結尾
                DAO 內的數據訪問方法必須足夠抽象的描述出對數據庫的基本 CRUD 操做；
                如： ICrossAdDAO( 接口 ) 、 CrossAdDAO( 實現類 )
           
            三、各類操做數據庫的 HQL 配置文件
                HQL 文件的個數原則上與系統的 Services 層的服務個數相等，且以服務名稱命名 HQL 文件；
                如： resource.hbm.xml

        二、服務層

            一、服務接口和實現
                服務接口和實現類必須徹底符合正常接口和實現類的命名規則；以工程定義的服務名爲主體，
                並統一以 」Serv」 結尾
                如： IResourceServ( 服務接口 ) 、 ResourceServ( 接口實現類 )

            二、服務接口方法
                方法名是一個動詞，採用大小寫混合的方式，第一個單詞的首字母小寫，其後單詞的首字母大寫。
           方法名儘量的描述出該方法的動做行爲。
                返回類型爲 Boolean 值：用「 is 」或「 has 」來開頭
                獲得某數據： get+ 數據描述名詞複數 + 數據類型；
                獲得全部數據： get+All+ 數據描述名詞複數 + 數據類型；
                經過 XXX 獲得 / 查詢某數據： get/query+ 數據描述名詞複數 + 數據類型 +By+ 條件；
                添加某數據： save/add+ 數據描述名詞 ()
                更新某數據： save/update+ 數據描述名詞；
                刪除某數據： delete/remove+ 數據描述名詞；

            三、業務對象
                業務名稱 +BO

            四、查詢參數對象
                凡是繼承 Abst***QuerySpec 的查詢參數類所有知足如下規則：
                Query+ 所要查詢的數據描述名詞 +Spec
                做爲參數傳入時，參數名必須爲：所要查詢的數據描述名詞 +Spec
                如： QueryProgramSpec

        三、MVC 層           

            一、Action 控制層
                Action 類名：功能模塊名稱 +Action ；
                Actoin 方法名稱儘量的描述出頁面遷移的去向
                如： LoginAction( 登陸用 action) ， toWelcome( 轉向歡迎頁的 action 方法 )

            二、資源文件
                系統全局資源文件： globalMessages_+ 字符編碼類型 +.properties
                功能模塊內部的資源文件： package.properties

         四、Spring 配置文件

            一、Action 相關配置文件
                文件目錄： WebRoot/WEB-INF/spring/action/ 功能模塊名稱 +_ApplicationContext.xml

            二、Services 相關配置文件
                文件目錄： WebRoot/WEB-INF/spring/services/Services_ApplicationContext.xml

            三、全局性配置文件
                文件目錄： WebRoot/WEB-INF/spring/工程名+_ApplicationContext.xml

        五、JSP 文件            採用完整的英文描述說明 JSP 所