SuppressionCommentFilter
Since Checkstyle 3.5
Description
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; // suppressed violation
//CHECKSTYLE:ON
public static final int var3 = 1;
// violation above, 'must match pattern'
//CHECKSTYLE:OFF
public static final int var4 = 1; // 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 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; // 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 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) {} // 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 Example4
{
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 = 1;
// violation above, 'must match pattern'
//CSOFF: ConstantName
public static final int var4 = 1; // 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 Example5
{
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 = 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) {} // 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 Example6
{
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 = 1;
// violation above, 'must match pattern'
//CSOFF ConstantID
public static final int var4 = 1; // 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 Example7
{
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 = 1;
// violation above, 'must match pattern'
//csoff ConstantName
//csoff IllegalCatch
public static final int var4 = 1; // 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 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; // 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