日期：2014/5/9
文：阿蜜果
為便于規范各位開發人員代碼、提高代碼質量，研發中心需要啟動代碼評審機制。為了加快代碼評審的速度，減少不必要的時間，可以加入一些代碼評審的靜態檢查工具，另外需要為研發中心配置統一的編碼模板和代碼格式化模板。
Java代碼規范、格式化和checkstyle檢查配置文檔下載地址：http://www.aygfsteel.com/Files/amigoxie/Java代碼規范、格式化和checkstyle檢查配置文檔.rar
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網站下載插件，網址如下：
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:/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>
posted on 2014-05-31 11:58
阿蜜果 閱讀(71818)
評論(2) 編輯 收藏 所屬分類:
項目管理