日期：2014/5/9

文：阿蜜果

         為便于規(guī)范各位開發(fā)人員代碼、提高代碼質(zhì)量，研發(fā)中心需要啟動(dòng)代碼評(píng)審機(jī)制。為了加快代碼評(píng)審的速度，減少不必要的時(shí)間，可以加入一些代碼評(píng)審的靜態(tài)檢查工具，另外需要為研發(fā)中心配置統(tǒng)一的編碼模板和代碼格式化模板。
      Java代碼規(guī)范、格式化和checkstyle檢查配置文檔下載地址：http://www.aygfsteel.com/Files/amigoxie/Java代碼規(guī)范、格式化和checkstyle檢查配置文檔.rar

1、配置統(tǒng)一的編碼模板

1.1 配置編碼模板

  在Eclipse或MyEclipse中點(diǎn)擊Window -> Preferences菜單，點(diǎn)擊左側(cè)的“Java”->“Code Style”->“Code Templates”，界面如下圖所示：  
   

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

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

例如文件注釋定義：
   

文件注釋定義中的文件作者取自所在系統(tǒng)登錄用戶，若不正確時(shí)，可點(diǎn)擊“Edit”按鈕后進(jìn)行修改。

選擇編碼模板文件完成后點(diǎn)擊下方的“Apply”按鈕應(yīng)用該模板文件，而后點(diǎn)擊“OK”按鈕完成設(shè)置。

1.2 使用編碼模板

1.2.1 創(chuàng)建類時(shí)自動(dòng)添加注釋

         在創(chuàng)建類時(shí)，勾選如下頁面的“Generate comments”選項(xiàng)，將會(huì)使新創(chuàng)建的類具有文件注釋和類注釋：     
      

         生成的類的內(nèi)容參考如下：

/**//*
 * XX公司源代碼，版權(quán)歸XX公司所有。
 * 
 * 項(xiàng)目名稱 : XXXXXXX
 * 創(chuàng)建日期 : May 9, 2014
 * 修改歷史 : 
 *     1. [May 9, 2014]創(chuàng)建文件 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 對(duì)已有類添加注釋

         對(duì)已有的類、方法添加注釋的方法：

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

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

2、配置統(tǒng)一的代碼格式化模板

2.1 配置代碼格式化模板

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

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

在格式化文件中定義了很多Java格式化規(guī)范，例如：

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

上行用于設(shè)置格式化時(shí)在一行達(dá)到150個(gè)字符（包括空格）時(shí)需要換行。

又如：

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

上行表示格式化時(shí)使用4個(gè)空格代替tab鍵。

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

2.2 配置使用4個(gè)空格代替tab鍵

tab鍵在不同的IDE、編輯器（例如EditPlus、UltraEdit等）中使用的空格數(shù)不同，因此為了統(tǒng)一，開發(fā)人員統(tǒng)一使用4個(gè)空格代替tab鍵（checkstyle會(huì)配置做相應(yīng)檢查）。

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

         在上圖中勾選“Insert spaces for tabs”（使用空格代替tab鍵），并設(shè)置“Displayed tab width”為4（即使用4個(gè)空格代替tab鍵）。

2.3 去掉對(duì)代碼注釋的格式化

         在使用“2.4 使用模板進(jìn)行格式化”進(jìn)行代碼格式化時(shí)，會(huì)將代碼注釋也進(jìn)行格式化，引起格式錯(cuò)亂，為避免其對(duì)注釋進(jìn)行格式化，采用的方法為：點(diǎn)擊“Java”->“Code Style”-> “Formatter”菜單，在右側(cè)選中模板后點(diǎn)擊“Edit”按鈕，在彈出的界面中選擇“Comments”的tab，如下圖所示：
     

         在上圖中對(duì)紅色區(qū)域的復(fù)選框取消勾選。

2.4 使用模板進(jìn)行格式化

         若要對(duì)某個(gè)文件進(jìn)行格式化，可使用如下幾種方法：

1） 打開文件后，在代碼區(qū)域采用“CTRL + SHIFT + F”快捷鍵；

2） 打開文件后，在代碼區(qū)域點(diǎn)擊右鍵選擇“Source”->“Format”功能。

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

3、配置checkstyle插件進(jìn)行代碼檢查

3.1 安裝Eclipse的checkstyle插件

可以從sourceforge網(wǎng)站下載插件，網(wǎng)址如下：

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

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

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

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

在某個(gè)目錄（eg. D:\Program Files (x86)\externalplugins）創(chuàng)建checkstyle\eclipse子目錄，將之前下載的插件下的features和plugins兩個(gè)文件下拷貝到該目錄下（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目錄下的內(nèi)容拷貝到Eclipse下的features目錄，將將下載的checkstyle插件的plugins目錄下的內(nèi)容拷貝到Eclipse下的plugins目錄。

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

點(diǎn)擊Eclipse或MyEclipse的“Help”->“Software Updates”->“Find and Install”，在彈出的窗口中選擇“Search for new features to install”單選框，接著在“Update sites to visit”窗口點(diǎn)擊“New Remote Site”按鈕，在該窗口輸入插件名稱和插件下載地址后點(diǎn)擊“OK”按鈕完成下載。

3.2 設(shè)置checkstyle配置文件

         Checkstyle插件安裝完成后，需要配置研發(fā)中心的checkstyle配置文件，配置文件參考《eclipse_checkstyle.xml》文件，該文件定義了研發(fā)中心需要用到的一些檢查規(guī)則。檢查項(xiàng)都加了注釋，具體內(nèi)容請(qǐng)參見附錄。

         點(diǎn)擊“Window”->“Preferences”菜單，在彈出窗口左側(cè)點(diǎn)擊“Checkstyle”，可看到右側(cè)默認(rèn)選中的是“Sun Checks”檢查規(guī)則，因?yàn)樵撘?guī)則要求比較嚴(yán)格，而且不適合本研發(fā)中心，所以需要自定義檢查文件。

         點(diǎn)擊“New”按鈕后，彈出“Check Configuration Properties”窗口，如下圖所示：
         

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

3.3 使用checkstyle

         選擇某個(gè)項(xiàng)目，點(diǎn)擊右鍵選擇“Checkstyle”，會(huì)出現(xiàn)如下菜單：

   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”對(duì)所選中的項(xiàng)目進(jìn)行檢查，檢查后對(duì)有問題的類會(huì)使用警告或錯(cuò)誤標(biāo)識(shí)。參考提示信息如下：   
     

         左側(cè)會(huì)顯示小圓圈，將鼠標(biāo)移動(dòng)到上面時(shí)將給出提示信息。

         使用checkstyle后，注釋、變量命名規(guī)范性、類中變量、構(gòu)造函數(shù)、方法的順序的檢查、行的長(zhǎng)度、文件的長(zhǎng)度、方法的長(zhǎng)度等都不需要手工進(jìn)行檢查，只需要在代碼評(píng)審時(shí)使用Checkstyle檢查即可。因此，讓代碼評(píng)審人員將側(cè)重點(diǎn)放在checkstyle檢查不出來的一些代碼的優(yōu)化問題。

3.4 checkstyle常見提示速查

         Checkstyle常見錯(cuò)誤和警告提示見下表所示：

4、附錄

4.1 eclipse_checkstyle.xml文件內(nèi)容

         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中的參數(shù)的檢查 -->   
        <module name="LocalFinalVariableName" />   
        <!-- 局部的非final型的變量，包括catch中的參數(shù)的檢查 -->   
        <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" />   
        <!-- 方法的參數(shù)名 -->   
        <module name="ParameterName " />   
        <!-- 常量名的檢查 -->   
        <module name="ConstantName" />
        <!-- 沒用的import檢查，比如：1.沒有被用到2.重復(fù)的3.import java.lang的4.import 與該類在同一個(gè)package的 -->   
        <module name="UnusedImports" />   

        <!-- 長(zhǎng)度方面的檢查 -->   
        <!-- 文件長(zhǎng)度不超過1500行 -->   
        <module name="FileLength">   
            <property name="max" value="1500" />   
        </module>   
        <!-- 每行不超過150個(gè)字-->   
        <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>   
        <!-- 方法的參數(shù)個(gè)數(shù)不超過5個(gè)。 并且不對(duì)構(gòu)造方法進(jìn)行檢查-->   
        <module name="ParameterNumber">   
            <property name="max" value="5" />   
            <property name="tokens" value="METHOD_DEF" />   
        </module>   

        <!-- 空格檢查 -->   
        <!-- 允許方法名后緊跟左邊圓括號(hào)"(" -->   
        <module name="MethodParamPad" />   
        <!-- 在類型轉(zhuǎn)換時(shí)，不允許左圓括號(hào)右邊有空格，也不允許與右圓括號(hào)左邊有空格 -->   
        <module name="TypecastParenPad" />

        <!-- 關(guān)鍵字 -->   
        <!--   
            每個(gè)關(guān)鍵字都有正確的出現(xiàn)順序。比如 public static final XXX 是對(duì)一個(gè)常量的聲明。如果使用 static 
            public final 就是錯(cuò)誤的   
        -->   
        <module name="ModifierOrder" />   
        <!-- 多余的關(guān)鍵字 -->   
        <module name="RedundantModifier" />   

        <!-- 對(duì)區(qū)域的檢查 -->   
        <!-- 不能出現(xiàn)空白區(qū)域 -->   
        <module name="EmptyBlock" />   
        <!-- 所有區(qū)域都要使用大括號(hào) -->   
        <module name="NeedBraces" />
        <!-- 多余的括號(hào) -->   
        <module name="AvoidNestedBlocks">   
            <property name="allowInSwitchCase" value="true" />   
        </module>   

        <!-- 編碼方面的檢查 -->   
        <!-- 不許出現(xiàn)空語句 -->   
        <module name="EmptyStatement" /> 
        <!-- 不允許魔法數(shù) -->   
        <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方法必須調(diào)用了super.clone() -->   
        <module name="SuperClone" />   
        <!-- finalize 必須調(diào)用了super.finalize() -->   
        <module name="SuperFinalize" />   
        <!-- 不能catch java.lang.Exception -->   
        <module name="IllegalCatch">   
            <property name="illegalClassNames" value="java.lang.Exception" />  
        </module>   
        <!-- 確保一個(gè)類有package聲明 -->   
        <module name="PackageDeclaration" />   
        <!-- 一個(gè)方法中最多有3個(gè)return -->   
        <module name="ReturnCount">   
            <property name="max" value="3" />   
            <property name="format" value="^$" />   
        </module>   
        <!--   
            根據(jù) Sun 編碼規(guī)范， class 或 interface 中的順序如下： 1.class 聲明。首先是 public,   
            然后是protected , 然后是 package level （不包括access modifier ） 最后是private .   
            (多個(gè)class放在一個(gè)java文件中的情況） 2.變量聲明。 首先是 public, 然后是protected然后是 package 
            level （不包括access modifier ） 最后是private . (多個(gè)class放在一個(gè)java文件中的情況）   
            3.構(gòu)造函數(shù) 4.方法   
        -->   
        <module name="DeclarationOrder" /> 
        <!-- 同一行不能有多個(gè)聲明 -->   
        <module name="MultipleVariableDeclarations" />   
        <!-- 不必要的圓括號(hào) -->   
        <module name="UnnecessaryParentheses" />    

        <!-- 雜項(xiàng) -->   
        <!-- 禁止使用System.out.println -->   
        <module name="GenericIllegalRegexp">   
            <property name="format" value="System\.out\.println" />   
            <property name="ignoreComments" value="true" />
        </module>
        <!-- 檢查并確保所有的常量中的L都是大寫的。因?yàn)樾懙淖帜竘跟數(shù)字1太象了 -->   
        <module name="UpperEll" />   
        <!-- 檢查數(shù)組類型的定義是String[] args，而不是String args[] -->   
        <module name="ArrayTypeStyle" />
        <!-- 檢查java代碼的縮進(jìn) 默認(rèn)配置：基本縮進(jìn) 4個(gè)空格，新行的大括號(hào)：0。新行的case 4個(gè)空格 -->   
        <module name="Indentation" />   
    </module> 
</module>