SuppressionCommentFilter

Since Checkstyle 3.5

Description

Filter SuppressionCommentFilter uses pairs of comments to suppress audit events.

Rationale: Sometimes there are legitimate reasons for violating a check. When this is a matter of the code in question and not personal preference, the best place to override the policy is in the code itself. Semi-structured comments can be associated with the check. This is sometimes superior to a separate suppressions file, which must be kept up-to-date as the source file is edited.

Note that the suppression comment should be put before the violation. You can use more than one suppression comment each on separate line.

Attention: This filter may only be specified within the TreeWalker module (<module name="TreeWalker"/>) and only applies to checks which are also defined within this module. To filter non-TreeWalker checks like RegexpSingleline, a SuppressWithPlainTextCommentFilter or similar filter must be used.

Notes

offCommentFormat and onCommentFormat must have equal paren counts.

SuppressionCommentFilter can suppress Checks that have Treewalker as parent module.

Properties

name description type default value since
checkC Control whether to check C style comments (/* ... */). boolean true 3.5
checkCPP Control whether to check C++ style comments (//). boolean true 3.5
checkFormat Specify check pattern to suppress. Pattern ".*" 3.5
idFormat Specify check ID pattern to suppress. Pattern null 8.24
messageFormat Specify message pattern to suppress. Pattern null 3.5
offCommentFormat Specify comment pattern to trigger filter to begin suppression. Pattern "CHECKSTYLE:OFF" 3.5
onCommentFormat Specify comment pattern to trigger filter to end suppression. Pattern "CHECKSTYLE:ON" 3.5

Examples

To configure a filter to suppress audit events (MemberNameCheck, ConstantNameCheck and IllegalCatchCheck have been taken here for reference) between a comment containing CHECKSTYLE:OFF and a comment containing CHECKSTYLE:ON: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionCommentFilter"/>
    <module name="MemberName"/>
    <module name="ConstantName"/>
    <module name="IllegalCatch"/>
  </module>
</module>

Example:

class InputSuppressionCommentFilter
{
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CHECKSTYLE:OFF
  int VAR2; // suppressed violation
  //CHECKSTYLE:ON

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //CHECKSTYLE:OFF
  public static final int var4; // suppressed violation
  //CHECKSTYLE:ON

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //CHECKSTYLE:OFF

    try {}
    catch(Exception ex) {} // suppressed violation
    catch(Error err) {} // suppressed violation

    //CHECKSTYLE:ON
  }
}

To configure a filter so that // stop constant check and // resume constant check marks legitimate constant names: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionCommentFilter">
      <property name="offCommentFormat" value="stop constant check"/>
      <property name="onCommentFormat" value="resume constant check"/>
      <property name="checkFormat" value="ConstantNameCheck"/>
    </module>
    <module name="MemberName"/>
    <module name="ConstantName"/>
    <module name="IllegalCatch"/>
  </module>
</module>

Example:

class InputSuppressionCommentFilter
{
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //stop constant check
  int VAR2; // violation , Name 'VAR2' must match pattern '^[a-z][a-zA-Z0-9]*$'
  //resume constant check

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //stop constant check
  public static final int var4; // suppressed violation
  //resume constant check

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //stop constant check

    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed
    catch(Error err) {} // violation , Catching 'Error' is not allowed

    //resume constant check
  }
}

To configure a filter so that UNUSED OFF:var and UNUSED ON: var marks a variable or parameter known not to be used by the code by matching the variable name in the message through a specified message in messageFormat: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionCommentFilter">
      <property name="offCommentFormat" value="ILLEGAL OFF\: (\w+)"/>
      <property name="onCommentFormat" value="ILLEGAL ON\: (\w+)"/>
      <property name="checkFormat" value="IllegalCatch"/>
      <property name="messageFormat" value="^Catching '$1' is not allowed.$"/>
    </module>
    <module name="MemberName"/>
    <module name="ConstantName"/>
    <module name="IllegalCatch"/>
  </module>
</module>

Example:

class InputSuppressionCommentFilter
{
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //ILLEGAL OFF: Exception
  int VAR2; // violation , Name 'VAR2' must match pattern '^[a-z][a-zA-Z0-9]*$'
  //ILLEGAL ON: Exception

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //ILLEGAL OFF: Exception
  public static final int var4;
  // violation above ,  Name 'var4' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'
  //ILLEGAL ON: Exception

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //ILLEGAL OFF: Exception

    try {}
    catch(Exception ex) {} // suppressed violation
    catch(Error err) {} // violation , Catching 'Error' is not allowed

    //ILLEGAL ON: Exception
  }
}

To configure a filter so that name of suppressed check mentioned in comment CSOFF: regexp and CSON: regexp mark a matching check: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionCommentFilter">
      <property name="offCommentFormat" value="CSOFF\: ([\w\|]+)"/>
      <property name="onCommentFormat" value="CSON\: ([\w\|]+)"/>
      <property name="checkFormat" value="$1"/>
    </module>
    <module name="MemberName"/>
    <module name="ConstantName"/>
    <module name="IllegalCatch"/>
  </module>
</module>

Example:

class InputSuppressionCommentFilter
{
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CSOFF: MemberName
  int VAR2; // suppressed violation
  //CSON: MemberName

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //CSOFF: ConstantName
  public static final int var4; // suppressed violation
  //CSON: ConstantName

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //CSOFF: IllegalCatch

    try {}
    catch(Exception ex) {} // suppressed violation
    catch(Error err) {} // suppressed violation

    //CSON: IllegalCatch
  }
}

To configure a filter to suppress all audit events between a comment containing CHECKSTYLE_OFF: ALMOST_ALL and a comment containing CHECKSTYLE_OFF: ALMOST_ALL except for the ConstantName check: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionCommentFilter">
      <property name="offCommentFormat" value="CHECKSTYLE_OFF: ALMOST_ALL"/>
      <property name="onCommentFormat" value="CHECKSTYLE_ON: ALMOST_ALL"/>
      <property name="checkFormat" value="^((?!(ConstantName)).)*$"/>
    </module>
    <module name="MemberName"/>
    <module name="ConstantName"/>
    <module name="IllegalCatch"/>
  </module>
</module>

Example:

class InputSuppressionCommentFilter
{
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CHECKSTYLE_OFF: ALMOST_ALL
  int VAR2; // suppressed violation
  //CHECKSTYLE_ON: ALMOST_ALL

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //CHECKSTYLE_OFF: ALMOST_ALL
  public static final int var4;
  // violation above ,  Name 'var4' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'
  //CHECKSTYLE_ON: ALMOST_ALL

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //CHECKSTYLE_OFF: ALMOST_ALL

    try {}
    catch(Exception ex) {} // suppressed violation
    catch(Error err) {} // suppressed violation

    //CHECKSTYLE_ON: ALMOST_ALL
  }
}

It is possible to specify an ID of checks, so that it can be leveraged by the SuppressionCommentFilter to skip validations. The following examples show how to skip validations near code that is surrounded with // CSOFF <ID> and // CSON <ID>, where ID is the ID of checks you want to suppress. In the config of SuppressionCommentFilter, checkFormat is set to '$1' which points to the ID written in the offCommentFormat and onCommentFormat. Config for such a case is written below: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionCommentFilter">
      <property name="offCommentFormat" value="CSOFF (\w+)"/>
      <property name="onCommentFormat" value="CSON (\w+)"/>
      <property name="idFormat" value="$1"/>
    </module>
    <module name="MemberName">
    <property name="id" value="MemberID"/>
    </module>
    <module name="ConstantName">
      <property name="id" value="ConstantID"/>
    </module>
    <module name="IllegalCatch">
      <property name="id" value="IllegalID"/>
    </module>
  </module>
</module>

Example:

class InputSuppressionCommentFilter
{
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CSOFF MemberID
  int VAR2; // suppressed violation
  //CSON: MemberID

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //CSOFF ConstantID
  public static final int var4; // suppressed violation
  //CSON ConstantID

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //CSOFF IllegalID

    try {}
    catch(Exception ex) {} // suppressed violation
    catch(Error err) {} // suppressed violation

    //CSON IllegalID
  }
}

Example of how to configure the check to suppress checks by name defined in comment. 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionCommentFilter">
      <property name="offCommentFormat" value="csoff (\w+)"/>
      <property name="onCommentFormat" value="cson (\w+)"/>
      <property name="checkFormat" value="$1"/>
    </module>
    <module name="MemberName"/>
    <module name="ConstantName"/>
    <module name="IllegalCatch"/>
  </module>
</module>

Example:

class InputSuppressionCommentFilter
{
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //csoff MemberName
  int VAR2; // suppressed violation
  //cson MemberName

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //csoff ConstantName
  //csoff IllegalCatch

  public static final int var4; // suppressed violation

  public void method1()
  {
    try {}
    catch(Exception ex) {} // suppressed violation

    try {}
    catch(Exception ex) {} // suppressed violation
    catch(Error err) {} // suppressed violation
  }

  //cson ConstantName
  //cson IllegalCatch

}

Example depicting use of checkC and checkCPP style comments 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SuppressionCommentFilter">
      <property name="checkC" value="true"/>
      <property name="checkCPP" value="false"/>
    </module>
    <module name="MemberName"/>
    <module name="ConstantName"/>
    <module name="IllegalCatch"/>
  </module>
</module>

Example:

class InputSuppressionCommentFilter
{
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CHECKSTYLE:OFF
  int VAR2; // violation , Name 'VAR2' must match pattern '^[a-z][a-zA-Z0-9]*$'
  //CHECKSTYLE:ON

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  /*CHECKSTYLE:OFF*/
  public static final int var4; // suppressed violation
  /*CHECKSTYLE:ON*/

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //CHECKSTYLE:OFF

    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed
    catch(Error err) {} // violation , Catching 'Error' is not allowed

    //CHECKSTYLE:ON
  }
}

Example of Usage

Package

com.puppycrawl.tools.checkstyle.filters

Parent Module

TreeWalker