最全详解CheckStyle的检查规则

本文收集了关于checkstyle的规则的基本所有属性，并按照规则分组，没有分组的，放在最后其他

1. Annotations（注解：5个）

• AnnotationUseStyle（注解使用风格）

这项检查可以控制要使用的注解的样式。

• MissingDeprecated（缺少deprecad）

检查java.lang.Deprecated注解或@deprecated的Javadoc标记是否同时存在。

• MissingOverride（缺少override）

当出现{@inheritDoc}的Javadoc标签时，验证java.lang.Override注解是否出现。

• PackageAnnotation（包注解）

这项检查可以确保所有包的注解都在package-info.java文件中。

• SuppressWarnings（抑制警告）

这项检查允许你指定不允许SuppressWarnings抑制哪些警告信息。你还可以指定一个TokenTypes列表，其中包含了所有不能被抑制的警告信息。

2. JavadocComments（Javadoc注释：6个）

• PackageJavadoc（包注释）

检查每个Java包是否都有Javadoc注释。默认情况下，它只允许使用一个package-info.java文件，但是可以将其配置为允许使用package.html文件。
如果两个文件都存在的话，就会报告错误，因为Javadoc工具不允许这种情况发生。

• MethodJavadoc（方法注释）

检查方法或构造器的Javadoc。默认不会检查未使用的throws。想要将未声明的java.lang.RuntimeExceptions也纳入文档，则需要将allowUndeclaredRTE属性设置为true。想要验证的可见范围是由scope属性指定的，默认值为Scope.PRIVATE。想要验证其他的可见范围，则需要将scope属性设置为相应的值。
如果不想显示由于参数或类型参数没有在注释中使用param标记进行说明而产生的错误消息，就需要勾选allowMissingParamTags属性。如果不想显示由于声明了抛出异常但没有在注释中使用throws标记进行说明而产生的错误消息，就需要勾选allowMissingThrowsTags属性。如果不想显示由于return语句是非void类型但没有在注释中使用return标记进行说明而产生的错误消息，就需要勾选allowMissingReturnTag属性。

由@Override注解标记的方法，它的Javadoc不是必需的。但是在Java 5下，无法为接口中的方法加上标记（已经在Java 6中修正）。因此，CheckStyle支持使用单个的{@inheritDoc}标记来代替所有其他的标记。例如，如果下面的方法实现了接口中的某个方法，那么Javadoc可以这样编写：
 

/** {@inheritDoc} */
public int checkReturnTag(final int aTagIndex,
                          JavadocTag[] aTags,
                          int aLineNo)

• StyleJavadoc（风格注释）

验证Javadoc注释，以便于确保它们的格式。可以检查以下注释：接口声明、类声明、方法声明、构造器声明、变量声明。

• TypeJavadoc（类型注释）

检查方法或构造器的Javadoc。默认不会检查author和version标记。想要验证的可见范围是由scope属性指定的，默认值为Scope.PRIVATE。想要验证其他的可见范围，则需要将scope属性设置为相应的值。想要为author标记或version标记定义格式，将authorFormat属性或versionFormat属性设置为指定的正则表达式即可。
如果不想显示由于类型参数没有在注释中使用param标记进行说明而产生的错误消息，就需要勾选allowMissingParamTags属性。

• VariableJavadoc（变量注释）

检查变量是否具有Javadoc注释。

• WriteTag（输出标记）

将Javadoc作为信息输出。可以作为样式表来使用，根据作者名排序报告。想要为一个标记定义格式，将tagFormat属性设置为相应的正则表达式即可。这项检查会使用两种不同的严重级别。当标记缺失时，使用标准的严重级别（Severity）。当标记存在时，使用附加的严重级别（tagSeverity）作为报告等级。

3. Naming Conventions（命名规约：12个）

• AbstractClassName（抽象类名称）

检查抽象类的名称是否遵守命名规约。

• ClassTypeParameterName（类的类型参数名称）

检查类的类型参数名称是否遵守命名规约。

• Constant Names（常量名称）

检查常量（用static final修饰的字段）的名称是否遵守命名规约。

• LocalFinalVariableNames（局部final变量名称）

检查局部final变量的名称是否遵守命名规约。

• LocalVariableNames（局部变量名称）

检查局部变量的名称是否遵守命名规约。

• MemberNames（成员名称）

检查成员变量（非静态字段）的名称是否遵守命名规约。

• MethodNames（方法名称）

检查方法名称是否遵守命名规约。

• MethodTypeParameterName（方法的类型参数名称）

检查方法的类型参数名称是否遵守命名规约。

• PackageNames（包名称）

检查包名称是否遵守命名规约。

• ParameterNames（参数名称）

检查参数名称是否遵守命名规约。

• StaticVariableNames（静态变量名称）

检查静态变量（用static修饰，但没用final修饰的字段）的名称是否遵守命名规约。

• TypeNames（类型名称）

检查类的名称是否遵守命名规约。                                                                                  format: 定义类和接口的命名规则
tokens: 定义规则适用的类型，例如：CLASS_DEF表示类，INTERFACE_DEF 表示接口

4. Headers（文件头：2个）

• Header（文件头）

检查源码文件是否开始于一个指定的文件头。headerFile属性可以指定一个文件，该文件包含了需要的文件头。还有另一种方法，文件头的内容可以直接在header属性中设置，而不使用外部文件。

ignoreLines属性可以设置行号，指定检查时忽略头文件中的哪些行。如果想要支持包含版权日期的文件头，那么这个属性就显得非常有用。例如，考虑下面的文件头：
line 1:
line 2: // checkstyle:
line 3: // Checks Java source code for adherence to a set of rules.
line 4: // Copyright (C) 2002  Oliver Burn
line 5:
因为年份信息会随着时间改变，通过将ignoreLines属性设置为4，你就可以告诉CheckStyle忽略第4行。

• RegularExpressionHeader（正则表达式文件头）

检查Java源码文件头部的每行是否匹配指定的正则表达式。

解释：在某些项目中，检查固定的头部是不足够的，例如，文件头可能需要一行版权信息，但是其中的年份信息会随着时间变化。

例如，考虑下面的文件头：

line  1: ^/{71}$
line  2: ^// checkstyle:$
line  3: ^// Checks Java source code for adherence to a set of rules\.$
line  4: ^// Copyright CC \d\d\d\d  Oliver Burn$
line  5: ^// Last modification by \$Author.*\$$
line  6: ^/{71}$
line  7:
line  8: ^package
line  9:
line 10: ^import
line 11:
line 12: ^/\*\*
line 13: ^ \*([^/]|$)
line 14: ^ \*/
第1行和第6行说明了如何更紧凑地表示71个'/'符号。第4行表示版权信息中的年份的格式是四位数字。第5行示范了如何在文件头部添加校正控制关键字。第12-14行是Javadoc的模板（第13行非常复杂，它可以抑制Javadoc注释中的冲突）。

5. Imports（导入：7个）

• AvoidStarImports（避免通配符导入）

检查没有import语句使用*符号。

解释：从一个包中导入所有的类会导致包之间的紧耦合，当一个新版本的库引入了命名冲突时，这样就有可能导致问题发生。

• AvoidStaticImports（避免静态导入）

检查没有静态导入语句。

解释：导入静态成员可能会导致类成员之间的命名冲突。导入静态成员可能会导致代码的可读性很差，因为读者可能会搞不清楚成员到底位于哪个类中。

• IllegalImports（非法导入）

检查是否导入了指定的非法包。默认情况下，这项检查会拒绝所有的sun.*包，因为直接使用sun.*包的程序肯定不是100%的纯Java程序。想要拒绝其他的包，将illegalPkgs属性设置为你指定的非法包列表即可。

• ImportOrderCheck（导入顺序检查）

检查导入包的顺序/分组。确保导入包的分组按照指定的顺序排列（例如，java.排在首位，javax.排在第二，以此类推），并且每个分组内导入的包都是按照字典序排列的。静态导入必须放在最后，并且也是按照字典序排列的。

• RedundantImports（多余导入）

检查是否存在多余的导入语句。如果一条导入语句满足以下条件，那么就是多余的：

1. 它是另一条导入语句的重复。也就是，一个类被导入了多次。

2. 从java.lang包中导入类，例如，导入java.lang.String。

3. 从当前包中导入类。

• UnusedImports（未使用导入）

检查未使用的导入语句。CheckStyle使用一种简单可靠的算法来报告未使用的导入语句。如果一条导入语句满足以下条件，那么就是未使用的：

1. 没有在文件中引用。这种算法不支持通配符导入，例如，java.io.*；。大多数IDE检查带有通配符的导入语句时，使用的算法非常复杂。

2. 它是另一条导入语句的重复。也就是，一个类被导入了多次。

3. 从java.lang包中导入类，例如，导入java.lang.String。

4. 从当前包中导入类。

5. 可选：在Javadoc注释中引用它。这项检查默认是关闭的，因为仅仅为了抽出文档而引入了一个编译时依赖是一个很坏的习惯。例如，当Javadoc注释中包含{@link Date}时，就会认为import java.util.Date被引用了。想要避免引入编译时依赖，可把Javadoc注释写成{@link