checkstyle之基础学习篇

A. 什么是checkstyle

wikipedia中给出的定义是这样的：

Checkstyle is a static code analysis tool used in software development for checking if Java source code complies with coding rules.

从定义中能够看到这样几点：

1. static

2. for JAVA

3. coding rule

首先怎样理解checkstyle是一种静态代码质量评估工具呢？statci means assessing the code quality without actually executing the code.(otherwise, it will be called dynamic code analysis)，同时因为静态分析是基于source code，无须编译或执行代码，所以速度较快。

其次，咱们能够经过配置module来配置对项目检查哪些coding rule。coding rule的制定好比能够参考sun的coding style或者google推出的coding style，好比google在今年二月份刚刚推出的最新版java coding style。

 

B. why checkstyle（在众多的code quality工具中为何选择checkstyle呢？）

1. Sonar

2. Simian

3. FindBugs

4. Cobertura

首先Sonar是一种开源的代码质量评估工具，提供不少插件，好比使用gradle做为构建工具，则经过运行gradle sA（short for sonar analysis），能够生成code quality report，该report直观提供项目中的tech debt的统计数据以及具体信息。但sonar的问题在于他能够简单的生成代码质量报告，却没法保证开发人员会去看这个报告，并据此对代码质量进行改进。与sonar不一样，经过将checkstyle引入到项目构建中，能够强制开发人员保证代码质量，不然会抛出异常，构建失败。

Simian(Similar Analyse)用于发现项目中的重复代码；

FindBugs：使用静态方法查找bug

Cobertura：用于计算java代码的测试覆盖率

 

C. 如何使用checkstyle

1. apply checkstyle plugin for gradle in build.gradle 

apply plugin: checkstyle

对项目配置该checkstyle插件以后，相应的checkstyle的gradle task也就会自动加进去，包括：checkstyleMain, checkstyleTest, check。其中check task与前两个task是dependent on的关系。

同时，配置该插件后，checkstyle会load文件config/checkstyle/checkstyle.xml做为配置文件，该文件的内容即为checkstyle rule。

2. run gradle check in command line

3. check the checkstyle report in the build output directory

 

D. checkstyle rule是怎样制定的呢？

经过module对checkstyle rule进行配置。

一般会有SuppressionFilter，经过xml文件指定不对某些file进行某些checkstyle rule的检查。

若是某个module没有指定，说明不对那个module对应的rule进行检查。

若是某个module被指定，但没有property配置，则说明使用该module对应rule的默认值进行check。

若是某个module被指定，而且配置了property，则说明使用特定的参数对该module对应的rule进行check。

若是一个module被屡次指定，而且配置不一样的property，则这些module之间是逻辑或的关系。

一般状况下，对于产品代码和测试代码会采用不一样的checkstyle rule的配置。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC
    "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
    "http://www.puppycrawl.com/dtds/configuration_1_3.dtd">

<!-- This is a checkstyle configuration file. For descriptions of
what the following rules do, please see the checkstyle configuration
page at http://checkstyle.sourceforge.net/config.html -->

<module name="Checker">
  <module name="RegexpSingleline">
    <property name="format" value="^(//| \*) Copyright (\([cC]\) )?[\d]{4}(\-[\d]{4})? (Google Inc\.).*$" />
    <property name="minimum" value="1" />
    <property name="maximum" value="10" />
    <property name="message" value="Google copyright is missing or malformed." />
    <property name="severity" value="error" />
  </module>

  <module name="FileTabCharacter">
    <!-- Checks that there are no tab characters in the file.
    -->
  </module>

  <module name="NewlineAtEndOfFile"/>

  <module name="RegexpSingleline">
    <!-- Checks that FIXME is not used in comments.  TODO is preferred.
    -->
    <property name="format" value="((//.*)|(\*.*))FIXME" />
    <property name="message" value='TODO is preferred to FIXME.  e.g. "TODO(johndoe): Refactor when v2 is released."' />
  </module>

  <module name="RegexpSingleline">
    <!-- Checks that TODOs are named.  (Actually, just that they are followed
         by an open paren.)
    -->
    <property name="format" value="((//.*)|(\*.*))TODO[^(]" />
    <property name="message" value='All TODOs should be named.  e.g. "TODO(johndoe): Refactor when v2 is released."' />
  </module>

  <!-- All Java AST specific tests live under TreeWalker module. -->
  <module name="TreeWalker">

    <!--

    IMPORT CHECKS

    -->

    <module name="RedundantImport">
      <!-- Checks for redundant import statements. -->
      <property name="severity" value="error"/>
    </module>

    <module name="ImportOrder">
      <!-- Checks for out of order import statements. -->

      <property name="severity" value="warning"/>
      <property name="groups" value="com.google,android,junit,net,org,java,javax"/>
      <!-- This ensures that static imports go first. -->
      <property name="option" value="top"/>
      <property name="tokens" value="STATIC_IMPORT, IMPORT"/>
    </module>

    <!--

    JAVADOC CHECKS

    -->

    <!-- Checks for Javadoc comments.                     -->
    <!-- See http://checkstyle.sf.net/config_javadoc.html -->
    <module name="JavadocMethod">
      <property name="scope" value="protected"/>
      <property name="severity" value="warning"/>
      <property name="allowMissingJavadoc" value="true"/>
      <property name="allowMissingParamTags" value="true"/>
      <property name="allowMissingReturnTag" value="true"/>
      <property name="allowMissingThrowsTags" value="true"/>
      <property name="allowThrowsTagsForSubclasses" value="true"/>
      <property name="allowUndeclaredRTE" value="true"/>
    </module>

    <module name="JavadocType">
      <property name="scope" value="protected"/>
      <property name="severity" value="error"/>
    </module>

    <module name="JavadocStyle">
      <property name="severity" value="warning"/>
    </module>

    <!--

    NAMING CHECKS

    -->

    <!-- Item 38 - Adhere to generally accepted naming conventions -->

    <module name="PackageName">
      <!-- Validates identifiers for package names against the
        supplied expression. -->
      <!-- Here the default checkstyle rule restricts package name parts to
        seven characters, this is not in line with common practice at Google.
      -->
      <property name="format" value="^[a-z]+(\.[a-z][a-z0-9]{1,})*$"/>
      <property name="severity" value="warning"/>
    </module>

    <module name="TypeNameCheck">
      <!-- Validates static, final fields against the
      expression "^[A-Z][a-zA-Z0-9]*$". -->
      <metadata name="altname" value="TypeName"/>
      <property name="severity" value="warning"/>
    </module>

    <module name="ConstantNameCheck">
      <!-- Validates non-private, static, final fields against the supplied
      public/package final fields "^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$". -->
      <metadata name="altname" value="ConstantName"/>
      <property name="applyToPublic" value="true"/>
      <property name="applyToProtected" value="true"/>
      <property name="applyToPackage" value="true"/>
      <property name="applyToPrivate" value="false"/>
      <property name="format" value="^([A-Z][A-Z0-9]*(_[A-Z0-9]+)*|FLAG_.*)$"/>
      <message key="name.invalidPattern"
               value="Variable ''{0}'' should be in ALL_CAPS (if it is a constant) or be private (otherwise)."/>
      <property name="severity" value="warning"/>
    </module>

    <module name="StaticVariableNameCheck">
      <!-- Validates static, non-final fields against the supplied
      expression "^[a-z][a-zA-Z0-9]*_?$". -->
      <metadata name="altname" value="StaticVariableName"/>
      <property name="applyToPublic" value="true"/>
      <property name="applyToProtected" value="true"/>
      <property name="applyToPackage" value="true"/>
      <property name="applyToPrivate" value="true"/>
      <property name="format" value="^[a-z][a-zA-Z0-9]*_?$"/>
      <property name="severity" value="warning"/>
    </module>

    <module name="MemberNameCheck">
      <!-- Validates non-static members against the supplied expression. -->
      <metadata name="altname" value="MemberName"/>
      <property name="applyToPublic" value="true"/>
      <property name="applyToProtected" value="true"/>
      <property name="applyToPackage" value="true"/>
      <property name="applyToPrivate" value="true"/>
      <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
      <property name="severity" value="warning"/>
    </module>

    <module name="MethodNameCheck">
      <!-- Validates identifiers for method names. -->
      <metadata name="altname" value="MethodName"/>
      <property name="format" value="^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$"/>
      <property name="severity" value="warning"/>
    </module>

    <module name="ParameterName">
      <!-- Validates identifiers for method parameters against the
        expression "^[a-z][a-zA-Z0-9]*$". -->
      <property name="severity" value="warning"/>
    </module>

    <module name="LocalFinalVariableName">
      <!-- Validates identifiers for local final variables against the
        expression "^[a-z][a-zA-Z0-9]*$". -->
      <property name="severity" value="warning"/>
    </module>

    <module name="LocalVariableName">
      <!-- Validates identifiers for local variables against the
        expression "^[a-z][a-zA-Z0-9]*$". -->
      <property name="severity" value="warning"/>
    </module>


    <!--

    LENGTH and CODING CHECKS

    -->

    <module name="LineLength">
      <!-- Checks if a line is too long. -->
      <property name="max" value="${com.puppycrawl.tools.checkstyle.checks.sizes.LineLength.max}" default="100"/>
      <property name="severity" value="error"/>

      <!--
        The default ignore pattern exempts the following elements:
          - import statements
          - long URLs inside comments
      -->

      <property name="ignorePattern"
          value="${com.puppycrawl.tools.checkstyle.checks.sizes.LineLength.ignorePattern}"
          default="^(package .*;\s*)|(import .*;\s*)|( *\* *https?://.*)$"/>
    </module>

    <module name="LeftCurly">
      <!-- Checks for placement of the left curly brace ('{'). -->
      <property name="severity" value="warning"/>
    </module>

    <module name="RightCurly">
      <!-- Checks right curlies on CATCH, ELSE, and TRY blocks are on
      the same line. e.g., the following example is fine:
      <pre>
        if {
          ...
        } else
      </pre>
      -->
      <!-- This next example is not fine:
      <pre>
        if {
          ...
        }
        else
      </pre>
      -->
      <property name="option" value="same"/>
      <property name="severity" value="warning"/>
    </module>

    <!-- Checks for braces around if and else blocks -->
    <module name="NeedBraces">
      <property name="severity" value="warning"/>
      <property name="tokens" value="LITERAL_IF, LITERAL_ELSE, LITERAL_FOR, LITERAL_WHILE, LITERAL_DO"/>
    </module>

    <module name="UpperEll">
      <!-- Checks that long constants are defined with an upper ell.-->
      <property name="severity" value="error"/>
    </module>

    <module name="FallThrough">
      <!-- Warn about falling through to the next case statement.  Similar to
      javac -Xlint:fallthrough, but the check is suppressed if a single-line comment
      on the last non-blank line preceding the fallen-into case contains 'fall through' (or
      some other variants which we don't publicized to promote consistency).
      -->
      <property name="reliefPattern"
       value="fall through|Fall through|fallthru|Fallthru|falls through|Falls through|fallthrough|Fallthrough|No break|NO break|no break|continue on"/>
      <property name="severity" value="error"/>
    </module>


    <!--

    MODIFIERS CHECKS

    -->

    <module name="ModifierOrder">
      <!-- Warn if modifier order is inconsistent with JLS3 8.1.1, 8.3.1, and
           8.4.3.  The prescribed order is:
           public, protected, private, abstract, static, final, transient, volatile,
           synchronized, native, strictfp
        -->
    </module>


    <!--

    WHITESPACE CHECKS

    -->

    <module name="WhitespaceAround">
      <!-- Checks that various tokens are surrounded by whitespace.
           This includes most binary operators and keywords followed
           by regular or curly braces.
      -->
      <property name="tokens" value="ASSIGN, BAND, BAND_ASSIGN, BOR,
        BOR_ASSIGN, BSR, BSR_ASSIGN, BXOR, BXOR_ASSIGN, COLON, DIV, DIV_ASSIGN,
        EQUAL, GE, GT, LAND, LE, LITERAL_CATCH, LITERAL_DO, LITERAL_ELSE,
        LITERAL_FINALLY, LITERAL_FOR, LITERAL_IF, LITERAL_RETURN,
        LITERAL_SYNCHRONIZED, LITERAL_TRY, LITERAL_WHILE, LOR, LT, MINUS,
        MINUS_ASSIGN, MOD, MOD_ASSIGN, NOT_EQUAL, PLUS, PLUS_ASSIGN, QUESTION,
        SL, SL_ASSIGN, SR_ASSIGN, STAR, STAR_ASSIGN"/>
      <property name="severity" value="error"/>
    </module>

    <module name="WhitespaceAfter">
      <!-- Checks that commas, semicolons and typecasts are followed by
           whitespace.
      -->
      <property name="tokens" value="COMMA, SEMI, TYPECAST"/>
    </module>

    <module name="NoWhitespaceAfter">
      <!-- Checks that there is no whitespace after various unary operators.
           Linebreaks are allowed.
      -->
      <property name="tokens" value="BNOT, DEC, DOT, INC, LNOT, UNARY_MINUS,
        UNARY_PLUS"/>
      <property name="allowLineBreaks" value="true"/>
      <property name="severity" value="error"/>
    </module>

    <module name="NoWhitespaceBefore">
      <!-- Checks that there is no whitespace before various unary operators.
           Linebreaks are allowed.
      -->
      <property name="tokens" value="SEMI, DOT, POST_DEC, POST_INC"/>
      <property name="allowLineBreaks" value="true"/>
      <property name="severity" value="error"/>
    </module>

    <module name="ParenPad">
      <!-- Checks that there is no whitespace before close parens or after
           open parens.
      -->
      <property name="severity" value="warning"/>
    </module>

  </module>
</module>