Java代码规范、格式化和checkstyle检查配置文档

       为便于规范各位开发人员代码、提高代码质量,研发中心需要启动代码评审机制。为了加快代码评审的速度,减少不必要的时间,可以加入一些代码评审的静态检查工具,另外需要为研发中心配置统一的编码模板和代码格式化模板。
      Java代码规范、格式化和checkstyle检查配置文档下载地址:http://www.blogjava.net/Files/amigoxie/Java代码规范、格式化和checkstyle检查配置文档.rar

1、配置统一的编码模板

1.1 配置编码模板

  在EclipseMyEclipse中点击Window -> Preferences菜单,点击左侧的“Java->Code Style->Code Templates”,界面如下图所示:  
   Java代码规范、格式化和checkstyle检查配置文档_第1张图片

         点击上图右侧的“Import”按钮,在弹出的文件选择窗口选择公司自己的编码模板,例如eclipse_templates.xml文件(仅提供参考,可自行修改)。在“Configure generated code and comments”区域有“Comments”和“Code”两个菜单,点开后可以看到各种类型的注释和编码模板定义:
      Java代码规范、格式化和checkstyle检查配置文档_第2张图片
      Java代码规范、格式化和checkstyle检查配置文档_第3张图片 

         可以点击上面的各种类型查看该模板文件的定义。

例如文件注释定义:
    Java代码规范、格式化和checkstyle检查配置文档_第4张图片

文件注释定义中的文件作者取自所在系统登录用户,若不正确时,可点击“Edit”按钮后进行修改。

选择编码模板文件完成后点击下方的“Apply”按钮应用该模板文件,而后点击“OK”按钮完成设置。

1.2 使用编码模板

1.2.1 创建类时自动添加注

      在创建类时,勾选如下页面的“Generate comments”选项,将会使新创建的类具有文件注释和类注释:     
      Java代码规范、格式化和checkstyle检查配置文档_第5张图片

         生成的类的内容参考如下:

/*
 * 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 配置代码格式化模板

EclipseMyEclipse中点击Window -> Preferences菜单,点击左侧的“Java->Code Style->Formatter”,界面如下图所示:   
    Java代码规范、格式化和checkstyle检查配置文档_第6张图片  

点击上图的“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、编辑器(例如EditPlusUltraEdit等)中使用的空格数不同,因此为了统一,开发人员统一使用4个空格代替tab键(checkstyle会配置做相应检查)。

EclipseMyEclipse中点击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子目录,将之前下载的插件下的featuresplugins两个文件下拷贝到该目录下(eg: D:\Program Files (x86)\externalplugins\checkstyle\eclipse)。

接着在eclipselinks目录下新建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”指定网址安装插件。

点击EclipseMyEclipse的“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”窗口,如下图所示:
       Java代码规范、格式化和checkstyle检查配置文档_第7张图片   

         在上图中选择“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常见错误和警告提示见下表所示:

 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>


你可能感兴趣的:(Java代码规范、格式化和checkstyle检查配置文档)