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 Example1
{
  int VAR1; // violation, Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CHECKSTYLE:OFF
  int VAR2; // filtered violation 'must match pattern'
  //CHECKSTYLE:ON

  public static final int var3 = 1;
  // violation above, 'must match pattern'

  //CHECKSTYLE:OFF
  public static final int var4 = 1; // filtered violation 'must match pattern'
  //CHECKSTYLE:ON

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

    //CHECKSTYLE:OFF

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

    //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 Example2
{
  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 = 1;
  // violation above, Name 'must match pattern'

  //stop constant check
  public static final int var4 = 1; // filtered violation 'must match pattern'
  //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 Example3
{
  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 = 1;
  // violation above, 'must match pattern'

  //ILLEGAL OFF: Exception
  public static final int var4 = 1;
  // violation above,  Name 'must match pattern'
  //ILLEGAL ON: Exception

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

    //ILLEGAL OFF: Exception

    try {}
    catch(Exception ex) {}
    // filtered violation above 'Catching 'Exception' is not allowed'
    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 Example4
{
  int VAR1; // violation, Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CSOFF: MemberName
  int VAR2; // filtered violation 'must match pattern'
  //CSON: MemberName

  public static final int var3 = 1;
  // violation above, 'must match pattern'

  //CSOFF: ConstantName
  public static final int var4 = 1; // filtered violation 'must match pattern'
  //CSON: ConstantName

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

    //CSOFF: IllegalCatch

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

    //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 Example5
{
  int VAR1; // violation, Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CHECKSTYLE_OFF: ALMOST_ALL
  int VAR2; // filtered violation 'must match pattern'
  //CHECKSTYLE_ON: ALMOST_ALL

  public static final int var3 = 1;
  // violation above, 'must match pattern'

  //CHECKSTYLE_OFF: ALMOST_ALL
  public static final int var4 = 1;
  // violation above, 'must match pattern'
  //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) {}
    // filtered violation above 'Catching 'Exception' is not allowed'
    catch(Error err) {}
    // filtered violation above 'Catching 'Error' is not allowed'

    //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 Example6
{
  int VAR1; // violation, Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CSOFF MemberID
  int VAR2; // filtered violation 'must match pattern'
  //CSON: MemberID

  public static final int var3 = 1;
  // violation above, 'must match pattern'

  //CSOFF ConstantID
  public static final int var4 = 1; // filtered violation 'must match pattern'
  //CSON ConstantID

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

    //CSOFF IllegalID

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

    //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 Example7
{
  int VAR1; // violation, Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //csoff MemberName
  int VAR2; // filtered violation 'must match pattern'
  //cson MemberName

  public static final int var3 = 1;
  // violation above, 'must match pattern'

  //csoff ConstantName
  //csoff IllegalCatch

  public static final int var4 = 1; // filtered violation 'must match pattern'

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

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

  //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 Example8
{
  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 = 1;
  // violation above, Name 'must match pattern'

  /*CHECKSTYLE:OFF*/
  public static final int var4 = 1; // filtered violation 'must match pattern'
  /*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
  }
}

SuppressionCommentFilter

Description

Notes

Properties

Examples

Example of Usage

Package

Parent Module