玩轉Eclipse — 自動程式碼規範檢查工具Checkstyle
大專案都需要小組中的多人共同完成，但是每個人都有自己的編碼習慣，甚至很多都是不正確的。那麼如何使小組所有開發人員都遵循某些編碼規範，以保證專案程式碼風格的一致性呢？如果硬性地要求每個開發人員在提交程式碼之前，都要對照的編碼規範將自己的程式碼檢查一遍，將是一個非常枯燥而且耗時的任務。Checkstyle是一個開原始碼分析工具，能夠幫助開發人員保證他們的程式碼遵循一定的程式碼規範。Checkstyle通過不斷地檢查你的程式碼，一旦發現有違反定義的程式碼規範的地方就立馬提示，以便開發人員能夠及時發現和修改不規範程式碼。Checkstyle在Eclipse中的外掛是eclipse-cs。
1. 安裝Checkstyle外掛
Eclipse選單欄上選擇 Help -> Install New Software...，進入如下安裝介面：
點選“Add...”開啟Add Repository對話方塊，如圖輸入Name和Location，點選“OK”。 選擇剛剛新增的JAutodoc，一直點選“Next >”直到安裝結束。
2. 配置Checkstyle
Eclipse選單欄上選擇 Window -> Preferences -> Checkstyle，進入如下設定介面：
在Global Check Configurations框中，列出可以選擇的檢查配置（Check Configuration），Default欄標記為對勾的預設配置。
如果想自己配置檢查選擇，可以點選“New...”按鈕新建一個配置，進入如下Check Configuration介面：
檢查配置的型別，可以有多種選擇。Internal Configuration型別是檢查配置存在於Eclipse內部；External Configuration型別相當於匯入一個已有的xml配置檔案。Checkstyle配置都是xml檔案。
如果想修改已有的配置，可以點選“Configure...”按鈕，開啟Checkstyle Configuration對話方塊，根據需要進行修改。
3. 使用Checkstyle
Checkstyle會在程式碼開發過程中，不斷地檢查程式碼規範，一般檢查的內容包括：
- Javadoc註釋
- 命名約定
- 標題
- Import
- 大小
- 空白
- 修飾符
- 程式碼
- 類設計
下面這段程式碼經過Checkstyle檢查之後，不符合規範的程式碼，底色都會被標記為淺黃色進行提示。點選行頭的提示標記，就會顯示具體不符合規範的地方。示例如下圖所示：
Reference
為便於規範各位開發人員程式碼、提高程式碼質量，研發中心需要啟動程式碼評審機制。為了加快程式碼評審的速度，減少不必要的時間，可以加入一些程式碼評審的靜態檢查工具，另外需要為研發中心配置統一的編碼模板和程式碼格式化模板。
1、配置統一的編碼模板
1.1 配置編碼模板
在Eclipse或MyEclipse中點選Window -> Preferences選單，點選左側的“Java”->“Code Style”->“Code Templates”，介面如下圖所示：
點選上圖右側的“Import”按鈕，在彈出的檔案選擇視窗選擇公司自己的編碼模板，例如eclipse_templates.xml檔案（僅提供參考，可自行修改）。在“Configure generated 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格式化規範，例如：
<setting id="org.eclipse.jdt.core.formatter.lineSplit" value="150"/>
上行用於設定格式化時在一行達到150個字元（包括空格）時需要換行。
又如：
<setting id="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”->“Code Style”-> “Formatter”選單，在右側選中模板後點擊“Edit”按鈕，在彈出的介面中選擇“Comments”的tab，如下圖所示：
在上圖中對紅色區域的複選框取消勾選。
2.4 使用模板進行格式化
若要對某個檔案進行格式化，可使用如下幾種方法：
1） 開啟檔案後，在程式碼區域採用“CTRL + SHIFT + F”快捷鍵；
2） 開啟檔案後，在程式碼區域點選右鍵選擇“Source”->“Format”功能。
【說明】建議採用“CTRL + Shift + F”快捷鍵。
3、配置checkstyle外掛進行程式碼檢查
3.1 安裝Eclipse的checkstyle外掛
可以從sourceforge網站下載外掛，網址如下：
該頁面有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:/Program Files (x86)/externalplugins/checkstyle。
【說明】此種方式便於管理外部Eclipse外掛。
二、下載checkstyle外掛資料夾後拷貝到Eclipse的和features和plugins目錄
此種方式將下載的checkstyle外掛的features目錄下的內容拷貝到Eclipse下的features目錄，將將下載的checkstyle外掛的plugins目錄下的內容拷貝到Eclipse下的plugins目錄。
三、使用 “Software Updates”->“Find and install”指定網址安裝外掛。
點選Eclipse或MyEclipse的“Help”->“Software Updates”->“Find and Install”，在彈出的視窗中選擇“Search for new features to install”單選框，接著在“Update sites 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>
checkStyle結果分析
1.Missing a Javadoc comment:缺少JavaDoc註釋 2.First sentence should end with a period:你的註釋的第一行文字結束應該加上一個"." 3.Expected @throws tag for 'Exception':在註釋中希望有@throws的說明,在方法前得註釋中新增這樣一行：* @throws Exception if has error(異常說明) 4.Parameter docType should be final:引數docType應該為final型別 解決方法：在引數docType前面加個final 5.Variable “ABC” must match pattern “^[a-z][a-zA-Z0-9]*$”變數“ABC”不符合命名規則“^[a-z][a-zA-Z0-9]*$”解決方法：把這個命名改成符合規則的命名 “aBC” 6.Utility classes should not have a public or default constructor. 介面中的內部類中不應該有公共的或者預設的構造方法 解決方法：在內部類中，定義一個私有的構造方法，然後內部類宣告為final型別。如果前面有static，那麼final還必須放在static之後 7.'{' is not preceded with whitespace.大括號後面必須空一格
8.'public' modifier out of order with the JLS suggestions. public順序錯誤
9.Method 'deleteChild' is not designed for extension - needs to be abstract, final or empty. 不是拓展或繼承的方法，必須指定abstract,final或空
1Type is missing a javadoc commentClass 缺少型別說明
2“{” should be on the previous line“{” 應該位於前一行。解決方法：把“{”放到上一行去
3Methos is missing a javadoc comment 方法前面缺少javadoc註釋。解決方法：新增javadoc註釋 類似這樣：
/**
* set default mock parameter.（方法說明）
* @param additionalParameters parameter additional(引數名稱)
* @return data manager(返回值說明)
* @throws Exception if has error(異常說明)
*/
4 Expected @throws tag for “Exception”在註釋中希望有@throws的說明
解決方法：在方法前得註釋中新增這樣一行：* @throws Exception if has error(異常說明)
5“.” Is preceeded with whitespace “.” 前面不能有空格。解決方法：把“（”前面的空格去掉
6“.” Is followed by whitespace“.” 後面不能有空格。解決方法：把“）”後面的空格去掉
7“=” is not preceeded with whitespace“=” 前面缺少空格。解決方法：在“=”前面加個空格
8“=” is not followed with whitespace“=” 後面缺少空格。解決方法：在“=”後面加個空格
9“}” should be on the same line“}” 應該與下條語句位於同一行。解決方法：把“}”放到下一行的前面
10Unused @param tag for “unused”沒有引數“unused”，不需註釋
解決方法：“* @param unused parameter additional(引數名稱)” 把這行unused引數的註釋去掉“
11Variable “CA” missing javadoc變數“CA”缺少javadoc註釋
解決方法：在“CA“變數前新增javad