CheckStyle安装、使用、配置.docx

CheckStyle说明文档目录CheckStyle安装使用11 安装12 使用12.1 勾选了“Use simple configuration”22.2 没有勾选“Use simple configuration”22.3 Exclude from checking22.4 Local Check Configuration33 代码规范配置文件43.1 配置代码规范43.1.1 新建规范文件43.1.2 代码规范配置选项53.2 Module配置63.2.1 Annotations63.2.2 BlockChecks83.2.3 Class Design103.2.4 Coding123.2.5 Duplicate Code243.2.6 Headers243.2.7 Imports253.2.8 Javadoc Comments293.2.9 Metrics323.2.10 Miscellaneous343.2.11 Modifiers393.2.12 Naming Conventions393.2.13 Regexp413.2.14 Size Violations423.2.15 Whitespace453.3 常见CheckStyle错误提示493.4 CheckStyle配置范例5149CheckStyle安装使用1 安装将features和plugins分别copy 到eclipse/plugins和/eclipse/features目录，重启Eclipse即完成checkstyle插件安装, 依次点击window Preferences，如果出现Checkstyle标签，说明安装成功：安装完成CheckStyle插件后，下面就是统一Eclipse的格式化模板，要让格式化出来的代码符合Checkstyle要求，将topsec_format.xml文件导入到eclipse，方法如下：Window PreferencesJavaCode StyleFormatter点击import按钮即完成导入,如图:建议：用ctrl+shift+f格式化代码。2 使用右键点击要进行代码规范检查的项目，选择CheckstyleCheck Code With CheckStyle, 即完成代码检查： 3 代码规范配置文件在eclipse的windows-Preferences找到CheckStyle进行配置。可以建立新的全局代码规范文件，并设为默认规范。3.1 配置代码规范3.1.1 新建规范文件点击“New”新建一个代码规范配置文件，如图3-1所示。图3-1 新建代码规范文件示意图在弹出对话框中，首先选择文件类型，包括Internal Configuration ,External Configuration File ,Remote Configuration ,Project Relative Configuration 四种类型。Internal Configuration：内建于eclipse的workspace中，位于workspace_dir/.metadata/.plugins/ net.sf.eclipsecs.core目录下，无法在项目目录中看到，文件内容可从已有的规范文件中导入，点击右下的“Import”按钮，找到相应的规范文件即可，此时是将外部分配置文件复制到workspace_dir/.metadata/.plugins/ net.sf.eclipsecs.core目录下，重新命名。External Configuration File：直接在项目中引用外部代码规范文件，并可以通过对规范进行配置来修改外部文件。适合团队协作开发。勾选“Protect CheckStyle Configuration File”防止源文件被改写。Remote Configuration：连接到远程代码规范文件，需要提供地址，用户名和密码。勾选“Cache Configuration File”来对远程文件进行缓存处理。此文件的配置不可修改，否则经过配置后会修改原规范文件，删除掉原规范文件的所有注释。Project Relative Configuration：当代码规范配置文件已经存在于workspace中的项目里时，适合于使用此选项。此处可以再确定配置类型后，直接从已有的规范文件中导入，点击“Import”按钮，找到相应的文件即可。此处可以点击“Additional Properties”按钮自定义一些变量，方便在后面配置自定义消息时使用。内建的变量如下：$basedir ： 当前工程所在的目录$project_loc ： 与$basedir相同$workspace_loc ： 当前workspace的目录$config_loc & $samedir ： 当前代码规范配置文件所在的目录当使用external, Remote or Project Relative Configuration选项创建配置文件时，可以讲变量写入到一个单独的文件中，文件名于配置文件的文件名一样，扩展名使用.properties，将该文件放在与配置文件相同的目录即可使用。如下所示：D:/path/to/my/config/myCheckConfiguration.xml D:/path/to/my/config/myCheckCperties3.1.2 代码规范配置选项在代码规范配置中，不同的逻辑内容比划分为不同的module，每个module下面有不同的子项目。如图3-2所示，从左侧条目数中，选择一个配置选项，点击“Add”按钮，弹出Module编辑框（如图3-3所示），配置完毕后即可添加到右侧的module集合中。配置的条目图标上会有小的对勾标识。图3-2 代码规范配置选项示意图图3-4 Module配置示意图在module配置对话框中General标签页里，Serverity表示所出现的问题的严重性，选项值有inherit、ignore、info、warning、error五个不同的等级。在下面的属性栏里，不同的module具有不同的属性，将在3.2节中介绍。在Advanced标签页中，Comment设定为对此规范的说明信息，id属性用于定义同一个检查类型的不同实例，可以定义不同的检查条件。下面是自定义的检查信息，即在发现代码不符合规范时，出现在Problems标签页中warnings下的信息，和将鼠标悬停在代码区域右侧的小放大镜上时出现的信息。设置信息时，可使用占位符。例如，使用正则表达式检查出包名规范问题时，提示信息：Name 0 must match pattern 1. ，其中0表示出现问题的包名，1表示正则表达式。底部的两个选项“Translated tokens”和“Sorted tokens”默认选中。上面所有的配置，其实都可以导出为一个xml文件。该文件中保存了所有经过配置的module信息，方便配置文件的导入导出。 3.2 Module配置在xml文件中进行module配置时，需要将各个module放在其parent module标签内，否则会报错。例如，大部分module都要放会TreeWalker标签内，因为他们都是TreeWalker的子module。3.2.1 Annotations对代码中的注释规范进行检查。 AnnotationUseStyle对注释的使用风格进行检查。1、 Propertiesa) elementStyle ： 元素参数的样式，默认值为compact_no_arrayi. expended：使用命名参数的方式进行注释，例如SuppressWarnings(value=unchecked,unused,)ii. compact ：该风格用于注释中的元素只有“value”一个，或者其他所有的元素都有默认值。例如，SuppressWarnings(unchecked,unused,) iii. compact_no_array ： 与compact相似，不同在于元素只有单个值时，不必放在数组中。如SuppressWarnings(unchecked)iv. ignore ：随意b) closingParens ： 是否保留结束括号，默认值为neveri. always ： 需要保留结束括号，例如，Deprecated()ii. never ： 不需要保留结束括号，例如，Deprecatediii. ignore ： 随意c) trailingArrayComma ： 是否在数组元素后尾随逗号，默认值为neveri. always ：总是在数组元素后尾随逗号。例如，SuppressWarnings(value=unchecked,unused,)ii. never ： 无序尾随逗号。例如，SuppressWarnings(value=unchecked,unused)iii. ignore ： 随意2、 xml代码 3、 Parent ModuleTreeWalker MissingDeprecated当java.lang.Deprecated注释或deprecated标签出现时，进行验证。1、 parent ModuleTreeWalker2、 xml代码 MissingOverride当java.lang.Override注释或inheritDoc标签出现时，进行验证。1、 PropertiesjavaFiveCompatibility ： 当此属性设置为true时，只会验证那些不含有externds、implements的类或接口，也不会验证匿名类，即，系统只会验证对Object方法的重写。Java5的兼容模式对此验证有较大限制，因此建议只在java5的源文件中使用。默认值为false。2、 Parent ModuleTreeWalker3、 Xml代码 PackageAnnotation该验证确保所有包的注释都放在package-info.java文件中。1、 Parent ModuleTreeWalker2、 Xml代码 SuppressWarnings该验证指明哪些warnings不要被SuppressWarnings隐藏。1、 Propertiesformat ： 该属性的值是一个正则表达式，符合此表达式的warnings都会被标识出来。默认值为“$|s+$”，表示“空字符串，或者是含有一个或多个空白字符的字符串”。Tokens ： 指明具体的关键字，包含在其中的不会被隐藏。，默认值为CLASS_DEF , INTERFACE_DEF , ENUM_DEF , ANNOTATION_DEF , ANNOTATION_FIELD_DEF ， ENUM_CONSTANT_DEF ， PARAMETER_DEF ， VARIABLE_DEF ， METHOD_DEF ， CTOR_DEF。2、 Parent ModuleTreeWalker3、 Xml代码 3.2.2 BlockChecks EmptyBlock对代码中的空块进行检查。1、 Properties(1)option：对代码块使用哪种策略，默认值为stmt。text：要求代码块中有文字即可，包括注释stmt：要求代码块中必须有代码。(2)tokens：要对那些关键字的代码块进行检查，默认值为所有的关键字。LITERAL_CATCH, LITERAL_DO, LITERAL_ELSE, LITERAL_FINALLY, LITERAL_IF, LITERAL_FOR, LITERAL_TRY, LITERAL_WHILE, INSTANCE_INIT STATIC_INIT2、 Parent moduleTreeWalker3、 Xml代码 LeftCurly对左侧大括号的放置位置进行检查。1、 Properties(1) option:左侧大括号放置位置的策略，默认值为eol。eol：左侧大括号必须放在行尾nl：左侧大括号必须放在下一新行nlow：若左侧大括号是放在语句的第一行，则使用eol规则，并将其计入到80个字符内，否则应用nl规则。例如：if (condition) /some statements if (condition1 & condition2 &condition3 & condition4)/some stetement(2) maxLineLength：每行的最大字符数，默认值为80(3) tokens：对那些关键字的代码块进行检查，默认检查所有关键字。CLASS_DEF, CTOR_DEF, INTERFACE_DEF, LITERAL_CATCH, LITERAL_DO, LITERAL_ELSE, LITERAL_FINALLY, LITERAL_FOR, LITERAL_IF, LITERAL_SWITCH, LITERAL_SYNCHRONIZED, LITERAL_TRY, LITERAL_WHILE, METHOD_DEF2、 Parent moduleTreeWalker3、 Xml代码 NeedBraces对包围代码块的括弧进行检查。1、Propertiestokens ： 检查那些关键字的代码块，默认全部检查。LITERAL_DO, LITERAL_ELSE, LITERAL_IF, LITERAL_FOR, LITERAL_WHILE2、Parent ModuleTreeWalker3、xml代码 RightCurly对关键字else、try和catch的右侧大括号放置位置进行检查。1、Properties(1)option : 右侧大括号放置位置策略，默认为samesame ： 与下一语句放在同一行alone ： 单独一行(2)tokens ： 检查哪些关键字的代码块。默认全部检查。LITERAL_TRY, LITERAL_CATCH, LITERAL_FINALLY, LITERAL_IF, LITERAL_ELSE(3)shouldStartLine：如果“”开始一个新行，是否要进行检查。默认为true。2、parent moduleTreeWalker3、xml代码 AvoidNestedBlocks验证代码块中是否有嵌套的代码块。1、PropertiesallowInSwitchCase ： 是否允许switchcase语句中有嵌套的代码块。默认为不允许。2、parent module TreeWalker3、xml代码3.2.3 Class Design VisibilityModifier验证类成员的可见性。只有static final成员可以是public，其他的成员必须是private，除非将属性protectedAllowed和packageAllowed设定为true。1、PropertiesprotectedAllowed ： 是否允许有保内可见的类成员。默认为false。packageAllowed ： 是否允许有可见性为protected的类成员，默认为false。publicMemberPattern：符合正则表达式的类成员可以设为public。默认为serialVersionUID$，即对象串行化标识。2、parent moduleTreeWalker3、xml代码 FinalClass检查声明为final的类只有似有构造方法。1、parent moduleTreeWalker2、xml代码 InterfaceIsType检查接口类型，例如javax.swing.SwingConstants将被该检查标识出来。1、PropertiesallowMarkerInterfaces ：是否允许出现没有方法或常量标记接口，如java.io.Serializable。默认值为true。2、parent moduleTreeWalker3、xml代码 HideUtilityClassConstructor确保工具类（即只包含静态方法和静态成员的类）没有public的构造方法。1、parent moduleTreeWalker2、xml代码 DesignForExtension确保对子类可扩展留有余地。1、parent moduleTreeWalker2、xml代码 MutableException检查Exception不可被修改，即Exception只有final的成员变量。1、Propertiesformat ： 通过正则表达式确定要检查哪些exception。默认值为“.*Exception$|.*Error$”，表示检查所有结尾含有“Exception”或Error“的exception。2、parent moduleTreeWalker3、xml代码 ThrowsCount检查抛出异常的语句的最大数目。1、Propertiesmax ： 允许出现throws语句的最大数目。默认值为12、parent moduleTreeWalker3、xml代码 3.2.4 Coding ArrayTrailingComma检查数组初始化时要尾随着逗号。例如，int a = new int 1, 2, 3,;当左右大括号在同一行时，可以不尾随逗号。例如，return new int 0 ;1、parent moduleTreeWalker2、xml代码 AvoidInlineConditionals检查inline的条件操作。如，String b = (a=null | a.length1) ? null : a.substring(1);1、parent moduleTreeWalker2、xml代码 CovariantEquals检查是否类既定义了equals()方法，又继承了equals(java.lang.Object)方法。张洋这样可能会产生无法预测的运行时异常。1、parent moduleTreeWalker2、xml代码 DoubleCheckedLocking对双检锁进行测定。含有双检锁的java代码可能无法正确的工作，所产生的bug难以跟踪，不易重复产生。双检锁举例：public class MySingleton private static theInstance = null; private MySingleton() public MySingleton getInstance() if ( theInstance = null ) / synchronize only if necessary synchronized( MySingleton.class ) if ( theInstance = null ) theInstance = new MySingleton(); 1、parent moduleTreeWalker2、xml代码 EmptyStatement对空语句（只有“；“）进行检查。1、parent moduleTreeWalker2、xml代码 EqualsAvoidNull对字符串比较进行检查，确保字符串值在左侧，例如，String str1 = “this is a example” ;“another example”.equals(str1) ;1、parent moduleTreeWalker2、xml代码 EqualsHashCode检查重写了equals()方法的类是否也重写了hashcode()方法。1、parent moduleTreeWalker2、xml代码 FinalLocalVariable检查始终没有改变过值的局部变量是否定义为final。也可检查没改变过值的参数是否定义为final。注意：当设置检查参数后，会忽略对接口方法和抽象方法参数的检查。1、Propertiestokens ：对哪种变量进行检查检查。默认值为VARIABLE_DEF，即对类成员进行检查。2、parent moduleTreeWalker3、xml代码 检查局部变量或参数是否隐藏了类中的变量。1、PropertiesTokens ： 检查哪类参数。默认值为PARAMETER_DEF, VARIABLE_DEFignoreFormat ： 忽略匹配正则表达式的名字。默认不启用该匹配。ignoreConstructorParameter ： 是否忽略构造函数中的参数，默认为false。ignoreSetter ： 是否忽略对setter方法的参数检查，默认为false。ignoreAbstractMethods ： 是否忽略对抽象方法的参数检查，默认为false。2、parent moduleTreeWalker3、xml代码 0 IllegalInstantiation当一个类有工厂方法实例化时，检查是否使用工厂方法实例化。例如，Boolean对象构造使用的是Boolean.valueOf()，而非构造函数。1、Propertiesclasses ： 哪些类不需要实例化，应使用工厂方法。默认为空。2、parent moduleTreeWalker3、xml代码 1 IllegalToken检查非法的标记。1、Propertiestokens ： 需要检查的分隔符。默认为，LITERAL_SWITCH, POST_INC, POST_DEC2、parent moduleTreeWalker3、xml代码 2 IllegalTokenText检查非法的标记文本内容。1、Propertiestokens：哪些标记要检查。默认为空。format：匹配该正则表达式的为非法文本内容。默认为空。ignoreCase：匹配时，是否大小写敏感。默认为falsemessage：出现非法内容时的提示信息。默认为空。2、parent moduleTreeWalker3、xml代码 3 InnerAssignment检查字表达式是否有复制语句，例如，”String s = Integer.toString(i = 2);”，for语句除外。1、Propertiestokens：哪些标记需要检查。默认全部检查。ASSIGN, BAND_ASSIGN, BOR_ASSIGN, BSR_ASSIGN, BXOR_ASSIGN, DIV_ASSIGN, MINUS_ASSIGN, MOD_ASSIGN, PLUS_ASSIGN, SL_ASSIGN, SR_ASSIGN, STAR_ASSIGN2、parent moduleTreeWalker3、xml代码 4 MagicNumber对魔法数进行检查，不应出现魔法数。，注，-1,0,1,2不认为是魔法数。1、Propertiestokens：哪些类型需要检查。默认全部检查。ignoreNumbers：哪些不认为是魔法数，默认为-1,0,1,22、parent moduleTreeWalker3、xml代码 5 MissingSwitchDefault检查switch语句块中是否有default子句。1、parent moduleTreeWalker2、xml代码6 ModifiedControlVariable检查在循环语句是否修改了控制变量。1、parent moduleTreeWalker2、xml代码7 RedundantThrows检查是否有重复被抛出的异常，包括，重复、未被查出的或另一个已声明的异常的子类。1、PropertiesallowUnchecked：是否允许有未被查出的异常存在于。默认为false。allowSubclasses：是否允许存在另一个异常的子类。默认为false。logLoadErrors：这个检查会载入throws标签提到的exception类，来检查它是否是运行时异常。若载入错误，该属性的设置会指定checkstyle的错误处理。若设置为false，则认为是类路径配置错误，TreeWalker完全停止对该类的操作。若设置为true，则checkstyle认为是javadoc的错别字或重构时产生的错误，并在checkstyle的普通报表中记录该问题。默认值为false。suppressLoadErrors：当logLoadErrors设置为true时，TreeWalker会完全处理该类，并显示在载入异常时出现的问题。若suppressLoadErrors设置为true，因logLoadErrors设置为true而产生的对规范的违背就不会被checkstyle记录。默认为false。2、parent moduleTreeWalker3、xml代码 8 SimplifyBooleanExpression对过于复杂的boolean表达式进行检查。1、parent moduleTreeWalker2、xml代码9 SimplifyBooleanReturn对复杂的boolean返回值表达式进行检查。1、parent moduleTreeWalker2、xml代码0 StringLiteralEquality检查字符串比较是否使用“=”或“！=”。1、parent moduleTreeWalker2、xml代码1 NestedIfDepth对if语句的嵌套进行检查。1、max：if语句的最大嵌套层数。默认为1。2、parent moduleTreeWalker3、xml代码 2 NestedTryDepth对if语句的嵌套进行检查。1、max：try语句的最大嵌套层数。默认为1。2、parent moduleTreeWalker3、xml代码 3 NoClone检查类是否对clone()方法进行了重写。建议不要重写。1、parent moduleTreeWalker2、xml代码4 NoFinalizer检查类中是否定义了finalize()方法。1、parent moduleTreeWalker2、xml代码5 SuperClone检查在覆盖clone()的方法里是否调用了super.clone()。1、parent moduleTreeWalker2、xml代码6 SuperFinalize检查在覆盖finalize()的方法里是否调用了super.finalize()。1、parent moduleTreeWalker2、xml代码7 IllegalCatch检查是否非法捕获了java.lang.Exception, java.lang.Error 或 java.lang.RuntimeException。1、PropertiesillegalClassNames：不要捕获的exception的名字。默认值为”java.lang.Exception, java.lang.Throwable, java.lang.RuntimeException”。2、parent moduleTreeWalker3、xml代码8 IllegalThrows检查是否抛出了非法的异常，如，java.lang.Error或java.lang.RuntimeException。1、PropertiesillegalClassNames：哪些异常不应抛出，默认值为java.lang.Throwable, java.lang.Error, java.lang.RuntimeException2、parent moduleTreeWalker3、xml代码9 PackageDeclaration检查是否每个类都有包声明。1、parent moduleTreeWalker2、xml代码0 JUnitTestCase该检查确保setUp()，tearDown()方法的正确命名，没有参数，返回void，并且可见性只能是public或protected。同时确保suite()方法的正确命名，无参数，返回junit.framewotk.Test，并且可见性只能是public或protected。1、parent moduleTreeWalker2、xml代码1 ReturnCount检查return语句的数目。1、Propertiesmax：允许return语句出现的最大数目，默认为2。format：哪些方法不检查。默认为”equals$”，即equals()方法不检查。2、parent moduleTreeWalker3、xml代码 2 IllegalType检查是佛有未使用过的类型。包括设声明、返回值和参数。1、Propertiestokens：要检查哪些关键字。默认全部检查。PARAMETER_DEF, VARIABLE_DEF METHOD_DEF。illegalClassNames：不能用在参数，类型声明和返回值的类型，默认为java.util.GregorianCalendar, java.util.Hashtable, java.util.HashSet, java.util.HashMap, java.util.ArrayList, java.util.LinkedList, java.util.LinkedHashMap, java.util.LinkedHashSet, java.util.TreeSet,