Java代碼規範、格式化和checkstyle檢查配置文檔

       

          爲便於規範各位開發人員代碼、提高代碼質量，研發中心需要啓動代碼評審機制。爲了加快代碼評審的速度，減少不必要的時間，可以加入一些代碼評審的靜態檢查工具，另外需要爲研發中心配置統一的編碼模板和代碼格式化模板。
      Java代碼規範、格式化和checkstyle檢查配置文檔下載地址：http://www.blogjava.net/Files/amigoxie/Java代碼規範、格式化和checkstyle檢查配置文檔.rar

1、配置統一的編碼模板

1.1 配置編碼模板

  在Eclipse或MyEclipse中點擊Window-> Preferences菜單，點擊左側的“Java”->“Code Style”->“CodeTemplates”，界面如下圖所示：  
   

         點擊上圖右側的“Import”按鈕，在彈出的文件選擇窗口選擇公司自己的編碼模板，例如eclipse_templates.xml文件（僅提供參考，可自行修改）。在“Configuregenerated code and comments”區域有“Comments”和“Code”兩個菜單，點開後可以看到各種類型的註釋和編碼模板定義：
     
       

         可以點擊上面的各種類型查看該模板文件的定義。

例如文件註釋定義：
   

文件註釋定義中的文件作者取自所在系統登錄用戶，若不正確時，可點擊“Edit”按鈕後進行修改。

選擇編碼模板文件完成後點擊下方的“Apply”按鈕應用該模板文件，而後點擊“OK”按鈕完成設置。

1.2 使用編碼模板

1.2.1 創建類時自動添加註釋

         在創建類時，勾選如下頁面的“Generate comments”選項，將會使新創建的類具有文件註釋和類註釋：     
      

         生成的類的內容參考如下：

/*
 * XX公司源代碼，版權歸XX公司所有。
 * 
 * 項目名稱 : XXXXXXX
 * 創建日期 : May 9, 2014
 * 修改歷史 : 
 *     1. [May 9, 2014]創建文件 by Xingxing,Xie
 */
package cn.amigo.eip.common;
/**
 * //TODO 添加類/接口功能描述
 * @author Xingxing,Xie
 */
public class CommentTest {
 
    /**
     * //TODO 添加方法功能描述
     * @param args
     */
    public static void main(String[] args) {
        // TODO Auto-generated method stub
    }
}

 

1.2.2 對已有類添加註釋

         對已有的類、方法添加註釋的方法：

   1） 選擇類的類名、方法名所在的行後，使用“ALT + SHIFT + J”快捷鍵；

   2） 在所在類或方法上輸入“/**”後按Enter鍵。

2、配置統一的代碼格式化模板

2.1 配置代碼格式化模板

在Eclipse或MyEclipse中點擊Window -> Preferences菜單，點擊左側的“Java”->“Code Style”->“Formatter”，界面如下圖所示：   
      

點擊上圖的“Import”按鈕，彈出格式化模板文件選擇框，選擇代碼格式化文件，例如eclipse_formatter-profile.xml文件（僅提供參考，可自行定義）。點擊下方的“Apply”按鈕應用該模板文件，而後點擊“OK”按鈕完成設置。

在格式化文件中定義了很多Java格式化規範，例如：

<settingid="org.eclipse.jdt.core.formatter.lineSplit"value="150"/>

上行用於設置格式化時在一行達到150個字符（包括空格）時需要換行。

又如：

<settingid="org.eclipse.jdt.core.formatter.tabulation.size"value="4"/>

上行表示格式化時使用4個空格代替tab鍵。

有興趣的人可以查看《eip_eclipse_formatter-profile.xml》文件的內容。

2.2 配置使用4個空格代替tab鍵

tab鍵在不同的IDE、編輯器（例如EditPlus、UltraEdit等）中使用的空格數不同，因此爲了統一，開發人員統一使用4個空格代替tab鍵（checkstyle會配置做相應檢查）。

在Eclipse或MyEclipse中點擊Window -> Preferences菜單，點擊左側的“General”->“Editors”->“Text Editors”，界面如下圖所示： 
    

         在上圖中勾選“Insert spaces for tabs”（使用空格代替tab鍵），並設置“Displayed tab width”爲4（即使用4個空格代替tab鍵）。

2.3 去掉對代碼註釋的格式化

         在使用“2.4 使用模板進行格式化”進行代碼格式化時，會將代碼註釋也進行格式化，引起格式錯亂，爲避免其對註釋進行格式化，採用的方法爲：點擊“Java”->“CodeStyle”-> “Formatter”菜單，在右側選中模板後點擊“Edit”按鈕，在彈出的界面中選擇“Comments”的tab，如下圖所示：
     

         在上圖中對紅色區域的複選框取消勾選。

2.4 使用模板進行格式化

         若要對某個文件進行格式化，可使用如下幾種方法：

1） 打開文件後，在代碼區域採用“CTRL + SHIFT + F”快捷鍵；

2） 打開文件後，在代碼區域點擊右鍵選擇“Source”->“Format”功能。

    【說明】建議採用“CTRL + Shift + F”快捷鍵。

3、配置checkstyle插件進行代碼檢查

3.1 安裝Eclipse的checkstyle插件

可以從sourceforge網站下載插件，網址如下：

http://sourceforge.net/projects/eclipse-cs/files/Eclipse%20Checkstyle%20Plug-in/

         該頁面有3.3.1 ～5.7.0版本的checkstyle插件，因爲5.0以上版本的checkstyle插件在筆者的MyEclipse 6.5版本上無法使用，所以下載的4.4.2版本，高版本的MyEclipse可嘗試新版本的checkstyle試試是否能成功使用。

安裝checkstyle插件的方法主要有如下三種：

一、在Eclipse下使用link方式鏈接插件

在某個目錄（eg. D:\Program Files(x86)\externalplugins）創建checkstyle\eclipse子目錄，將之前下載的插件下的features和plugins兩個文件下拷貝到該目錄下（eg: D:\Program Files (x86)\externalplugins\checkstyle\eclipse）。

接着在eclipse的links目錄下新建checkstyle.xml文件，在該文件中添加一行寫上需要鏈接的插件地址，例如：path=D:/ProgramFiles (x86)/externalplugins/checkstyle。

【說明】此種方式便於管理外部Eclipse插件。

二、下載checkstyle插件文件夾後拷貝到Eclipse的和features和plugins目錄

此種方式將下載的checkstyle插件的features目錄下的內容拷貝到Eclipse下的features目錄，將將下載的checkstyle插件的plugins目錄下的內容拷貝到Eclipse下的plugins目錄。

三、使用 “Software Updates”->“Find and install”指定網址安裝插件。

點擊Eclipse或MyEclipse的“Help”->“SoftwareUpdates”->“Find and Install”，在彈出的窗口中選擇“Search for new features to install”單選框，接着在“Updatesites to visit”窗口點擊“New Remote Site”按鈕，在該窗口輸入插件名稱和插件下載地址後點擊“OK”按鈕完成下載。

3.2 設置checkstyle配置文件

        Checkstyle插件安裝完成後，需要配置研發中心的checkstyle配置文件，配置文件參考《eclipse_checkstyle.xml》文件，該文件定義了研發中心需要用到的一些檢查規則。檢查項都加了註釋，具體內容請參見附錄。

         點擊“Window”->“Preferences”菜單，在彈出窗口左側點擊“Checkstyle”，可看到右側默認選中的是“Sun Checks”檢查規則，因爲該規則要求比較嚴格，而且不適合本研發中心，所以需要自定義檢查文件。

         點擊“New”按鈕後，彈出“Check Configuration Properties”窗口，如下圖所示：
         

         在上圖中選擇“Type”爲“External Configuration File”（外部配置文件），在“Location”行點擊“Browse”按鈕瀏覽選擇checkstyle的配置文件，例如eclipse_checkstyle.xml文件（僅供參考，可自行定義），並輸入“Name”行的值，例如“eclipse_checkstyle”，點擊“OK”按鈕完成導入操作。回到Checkstyle主頁面選擇剛纔添加的文件，點擊“Set As Default”將其設置爲默認checkstyle檢查文件。

3.3 使用checkstyle

         選擇某個項目，點擊右鍵選擇“Checkstyle”，會出現如下菜單：

   1） Configure project(s) from blueprint：指定工程加入Checkstyle檢查；

   2） Activate Checkstyle：激活Checkstyle；

   3） Deactivate Checkstyle：取消激活Checkstyle；

   4） Check code with Checkstyle：使用Checkstyle檢查代碼；

   5） Clear Checkstyle violations：去掉Checkstyle的檢查提示。

  選擇“Check code with Checkstyle”對所選中的項目進行檢查，檢查後對有問題的類會使用警告或錯誤標識。參考提示信息如下：   
     

         左側會顯示小圓圈，將鼠標移動到上面時將給出提示信息。

         使用checkstyle後，註釋、變量命名規範性、類中變量、構造函數、方法的順序的檢查、行的長度、文件的長度、方法的長度等都不需要手工進行檢查，只需要在代碼評審時使用Checkstyle檢查即可。因此，讓代碼評審人員將側重點放在checkstyle檢查不出來的一些代碼的優化問題。

3.4 checkstyle常見提示速查

        Checkstyle常見錯誤和警告提示見下表所示：

錯誤提示	錯誤說明
missing a javadoc comment	缺少類註釋
Line longer than X characters	行長度超過X個字符(包括空格)
Return count is X(max allowed 3)	一個方法內的返回數量是X(最大值只能爲3)
Nested if-else depth is X(max allowed is 3)	最大的if-else嵌套層數爲X(最大隻能爲3)
Array brackets at illegal position	數組的方括號“[]”的位置不正確（檢查數組類型的定義是String[] args，而不是String args[]）
Line matchs the illegal pattern 'System\.out\.println'	本行包含System.out.println語句
ctor def modifier at indentation level 8 not at corrent indentation 4	縮進不正確，一般是因爲沒有在Eclipse中使用4個空格代替tab鍵引起。
'static' modifier out of order with the JLS suggestions	static修飾符沒有按照JLS的建議來排序(eg.寫成public final static...應該改成public static final)
Name 'X' must match pattern '^[A-Z][A-Z0-9][_A-Z0-9+]$'(正則表達式)	名稱不符合正則表達式'^[A-Z][A-Z0-9][_A-Z0-9+]$'(即爲大寫字母，數字、下劃線等)。 一般在靜態變量沒有大寫時提示，包名不是全部消息時提示，類名不是大寫開頭時提示，方法名不是小寫開頭時提示
Variable access definition in wrong order	變量定義順序不正確(例如在類成員變量定義時，將private類型的變量定義在public類型的變量之前)
Static variable definition in wrong order	靜態變量定義順序不正確(例如在構造函數之後定義靜態變量)
Instance variable definition in wrong order	成員變量定義順序不正確(例如在構造函數之後定義成員變量)
X is a magic number	X是一個魔術數字(非0、1、2的數字)
if construct must use '{}'	if結構必須使用'{}'
Got an exception - Unexpected character 0xfffd in identifier	因爲沒有設置checkstyle配置文件的charset爲UTF-8，而類文件使用UTF-8編碼，並且含有中文
“{” should be on the previous line	“{” 應該位於前一行
Methods is missing a javadoc comment	方法前面缺少javadoc註釋
Expected @throws tag for “Exception”	在註釋中希望有@throws的說明
“.” Is preceeded with whitespace	“.” 前面不能有空格
“.” Is followed by whitespace	“.” 後面不能有空格
“=” is not preceeded with whitespace“=”	前面缺少空格
“=” is not followed with whitespace	“=” 後面缺少空格
“}” should be on the same line	“}” 應該與下條語句位於同一行
Unused @param tag for “unused”	沒有參數“unused”，不需註釋
Variable “X” missing javadoc	變量“CA”缺少javadoc註釋
Line contains a tab character	行含有”tab” 字符
Redundant “Public” modifier	冗餘的“public” modifier
final modifier out of order with the JSL suggestion	final修飾符的順序錯誤
Avoid using the “.*” form of import	Import格式避免使用“.*”
Redundant import from the same package	從同一個包中Import內容
Unused import-X Import	import的X類沒有被使用
Duplicate import to line X	重複Import同一個內容
Import from illegal package	從非法包中 Import內容
“while” construct must use “{}”	“while” 語句缺少“{}”
Variable “X” must be private and have accessor method	變量“X”應該是private的，並且有調用它的方法
Variable “X” must match pattern “^[a-z][a-zA-Z0-9]*$”	變量“X”不符合命名規則“^[a-z][a-zA-Z0-9]*$”
“(” is followed by whitespace	“(” 後面不能有空格
“)” is proceeded by whitespace	“)” 前面不能有空格

4、附錄

4.1 eclipse_checkstyle.xml文件內容

        Checkstyle配置文件eclipse_checkstyle如下所示：

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
          "-//Puppy Crawl//DTD Check Configuration 1.2//EN"
          "http://www.puppycrawl.com/dtds/configuration_1_2.dtd">

<module name="Checker">
         <property name="severity" value="warning"/>
    <module name="StrictDuplicateCode">
        <property name="charset" value="utf-8" />   
    </module>   

    <module name="TreeWalker">   
        <!-- javadoc的檢查 -->   
        <!-- 檢查所有的interface和class -->   
        <module name="JavadocType" />   

        <!-- 命名方面的檢查 -->   
        <!-- 局部的final變量，包括catch中的參數的檢查 -->   
        <module name="LocalFinalVariableName" />   
        <!-- 局部的非final型的變量，包括catch中的參數的檢查 -->   
        <module name="LocalVariableName" />   
        <!-- 包名的檢查（只允許小寫字母） -->   
        <module name="PackageName">   
            <property name="format" value="^[a-z]+(\.[a-z][a-z0-9]*)*$" />   
        </module>   
        <!-- 僅僅是static型的變量（不包括static final型）的檢查 -->   
        <module name="StaticVariableName" />   
        <!-- 類型(Class或Interface)名的檢查 -->   
        <module name="TypeName" />   
        <!-- 非static型變量的檢查 -->   
        <module name="MemberName" />   
        <!-- 方法名的檢查 -->   
        <module name="MethodName" />   
        <!-- 方法的參數名 -->   
        <module name="ParameterName " />   
        <!-- 常量名的檢查 -->   
        <module name="ConstantName" />
        <!-- 沒用的import檢查，比如：1.沒有被用到2.重複的3.import java.lang的4.import 與該類在同一個package的 -->   
        <module name="UnusedImports" />   

        <!-- 長度方面的檢查 -->   
        <!-- 文件長度不超過1500行 -->   
        <module name="FileLength">   
            <property name="max" value="1500" />   
        </module>   
        <!-- 每行不超過150個字-->   
        <module name="LineLength">   
            <property name="max" value="150" />   
        </module>   
        <!-- 方法不超過150行 -->   
        <module name="MethodLength">   
            <property name="tokens" value="METHOD_DEF" />   
            <property name="max" value="150" />   
        </module>   
        <!-- 方法的參數個數不超過5個。 並且不對構造方法進行檢查-->   
        <module name="ParameterNumber">   
            <property name="max" value="5" />   
            <property name="tokens" value="METHOD_DEF" />   
        </module>   

        <!-- 空格檢查 -->   
        <!-- 允許方法名後緊跟左邊圓括號"(" -->   
        <module name="MethodParamPad" />   
        <!-- 在類型轉換時，不允許左圓括號右邊有空格，也不允許與右圓括號左邊有空格 -->   
        <module name="TypecastParenPad" />

        <!-- 關鍵字 -->   
        <!--   
            每個關鍵字都有正確的出現順序。比如 public static final XXX 是對一個常量的聲明。如果使用 static 
            public final 就是錯誤的   
        -->   
        <module name="ModifierOrder" />   
        <!-- 多餘的關鍵字 -->   
        <module name="RedundantModifier" />   

        <!-- 對區域的檢查 -->   
        <!-- 不能出現空白區域 -->   
        <module name="EmptyBlock" />   
        <!-- 所有區域都要使用大括號 -->   
        <module name="NeedBraces" />
        <!-- 多餘的括號 -->   
        <module name="AvoidNestedBlocks">   
            <property name="allowInSwitchCase" value="true" />   
        </module>   

        <!-- 編碼方面的檢查 -->   
        <!-- 不許出現空語句 -->   
        <module name="EmptyStatement" /> 
        <!-- 不允許魔法數 -->   
        <module name="MagicNumber">   
            <property name="tokens" value="NUM_DOUBLE, NUM_INT" />   
        </module>
        <!-- 多餘的throw -->   
        <module name="RedundantThrows" /> 
        <!-- String的比較不能用!= 和 == -->   
        <module name="StringLiteralEquality" />   
        <!-- if最多嵌套3層 -->   
        <module name="NestedIfDepth">   
            <property name="max" value="3" />   
        </module>   
        <!-- try最多被嵌套2層 -->   
        <module name="NestedTryDepth">   
            <property name="max" value="2" />   
        </module>   
        <!-- clone方法必須調用了super.clone() -->   
        <module name="SuperClone" />   
        <!-- finalize 必須調用了super.finalize() -->   
        <module name="SuperFinalize" />   
        <!-- 不能catch java.lang.Exception -->   
        <module name="IllegalCatch">   
            <property name="illegalClassNames" value="java.lang.Exception" />  
        </module>   
        <!-- 確保一個類有package聲明 -->   
        <module name="PackageDeclaration" />   
        <!-- 一個方法中最多有3個return -->   
        <module name="ReturnCount">   
            <property name="max" value="3" />   
            <property name="format" value="^$" />   
        </module>   
        <!--   
            根據 Sun 編碼規範， class 或 interface 中的順序如下： 1.class 聲明。首先是 public,   
            然後是protected , 然後是 package level （不包括access modifier ） 最後是private .   
            (多個class放在一個java文件中的情況） 2.變量聲明。 首先是 public, 然後是protected然後是 package 
            level （不包括access modifier ） 最後是private . (多個class放在一個java文件中的情況）   
            3.構造函數 4.方法   
        -->   
        <module name="DeclarationOrder" /> 
        <!-- 同一行不能有多個聲明 -->   
        <module name="MultipleVariableDeclarations" />   
        <!-- 不必要的圓括號 -->   
        <module name="UnnecessaryParentheses" />    

        <!-- 雜項 -->   
        <!-- 禁止使用System.out.println -->   
        <module name="GenericIllegalRegexp">   
            <property name="format" value="System\.out\.println" />   
            <property name="ignoreComments" value="true" />
        </module>
        <!-- 檢查並確保所有的常量中的L都是大寫的。因爲小寫的字母l跟數字1太象了 -->   
        <module name="UpperEll" />   
        <!-- 檢查數組類型的定義是String[] args，而不是String args[] -->   
        <module name="ArrayTypeStyle" />
        <!-- 檢查java代碼的縮進 默認配置：基本縮進 4個空格，新行的大括號：0。新行的case 4個空格 -->   
        <module name="Indentation" />   
    </module> 
</module>        

 

聲明：本文爲轉自博客園，原文地址：http://www.blogjava.net/amigoxie/archive/2014/05/31/414287.html。