Class SuppressionCommentFilter
- All Implemented Interfaces:
Configurable
,Contextualizable
,TreeWalkerFilter
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.
offCommentFormat
and onCommentFormat
must have equal
paren counts.
SuppressionCommentFilter can suppress Checks that have Treewalker as parent module.
-
Property
offCommentFormat
- Specify comment pattern to trigger filter to begin suppression. Type isjava.util.regex.Pattern
. Default value is"CHECKSTYLE:OFF"
. -
Property
onCommentFormat
- Specify comment pattern to trigger filter to end suppression. Type isjava.util.regex.Pattern
. Default value is"CHECKSTYLE:ON"
. -
Property
checkFormat
- Specify check pattern to suppress. Type isjava.util.regex.Pattern
. Default value is".*"
. -
Property
messageFormat
- Specify message pattern to suppress. Type isjava.util.regex.Pattern
. Default value isnull
. -
Property
idFormat
- Specify check ID pattern to suppress. Type isjava.util.regex.Pattern
. Default value isnull
. -
Property
checkCPP
- Control whether to check C++ style comments (//
). Type isboolean
. Default value istrue
. -
Property
checkC
- Control whether to check C style comments (/* ... */
). Type isboolean
. Default value istrue
.
To configure a filter to suppress audit events between a comment containing
CHECKSTYLE:OFF
and a comment containing CHECKSTYLE:ON
:
<module name="TreeWalker"> ... <module name="SuppressionCommentFilter"/> ... </module>
To configure a filter to suppress audit events between a comment containing line
BEGIN GENERATED CODE
and a comment containing line END GENERATED CODE
:
<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="BEGIN GENERATED CODE"/> <property name="onCommentFormat" value="END GENERATED CODE"/> </module>
//BEGIN GENERATED CODE @Override public boolean equals(Object obj) { ... } // No violation events will be reported @Override public int hashCode() { ... } // No violation events will be reported //END GENERATED CODE . . .
To configure a filter so that // stop constant check
and
// resume constant check
marks legitimate constant names:
<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="stop constant check"/> <property name="onCommentFormat" value="resume constant check"/> <property name="checkFormat" value="ConstantNameCheck"/> </module>
//stop constant check public static final int someConstant; // won't warn here //resume constant check public static final int someConstant; // will warn here as constant's name doesn't match the // pattern "^[A-Z][A-Z0-9]*$"
To configure a filter so that UNUSED OFF: <i>var</i>
and
UNUSED ON: <i>var</i>
marks a variable or parameter known not to be
used by the code by matching the variable name in the message:
<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="UNUSED OFF\: (\w+)"/> <property name="onCommentFormat" value="UNUSED ON\: (\w+)"/> <property name="checkFormat" value="Unused"/> <property name="messageFormat" value="^Unused \w+ '$1'.$"/> </module>
private static void foo(int a, int b) // UNUSED OFF: b { System.out.println(a); } private static void foo1(int a, int b) // UNUSED ON: b { System.out.println(a); }
To configure a filter so that name of suppressed check mentioned in comment
CSOFF: <i>regexp</i>
and CSON: <i>regexp</i>
mark a matching check:
<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="CSOFF\: ([\w\|]+)"/> <property name="onCommentFormat" value="CSON\: ([\w\|]+)"/> <property name="checkFormat" value="$1"/> </module>
public static final int lowerCaseConstant; // CSOFF: ConstantNameCheck public static final int lowerCaseConstant1; // CSON: ConstantNameCheck
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 EqualsHashCode check:
<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="CHECKSTYLE_OFF: ALMOST_ALL"/> <property name="onCommentFormat" value="CHECKSTYLE_ON: ALMOST_ALL"/> <property name="checkFormat" value="^((?!(EqualsHashCode)).)*$"/> </module>
public static final int array []; // CHECKSTYLE_OFF: ALMOST_ALL private String [] strArray; private int array1 []; // CHECKSTYLE_ON: ALMOST_ALL
To configure a filter to suppress Check's violation message
which matches specified message in messageFormat
(so suppression will be not only by Check's name, but by message text
additionally, as the same Check could report different by message format violations)
between a comment containing stop
and comment containing resume
:
<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="stop"/> <property name="onCommentFormat" value="resume"/> <property name="checkFormat" value="IllegalTypeCheck"/> <property name="messageFormat" value="^Declaring variables, return values or parameters of type 'GregorianCalendar' is not allowed.$"/> </module>
Code before filter above is applied with Check's audit events:
... // Warning below: Declaring variables, return values or parameters of type 'GregorianCalendar' // is not allowed. GregorianCalendar calendar; // Warning below here: Declaring variables, return values or parameters of type 'HashSet' // is not allowed. HashSet hashSet; ...
Code after filter is applied:
... //stop GregorianCalendar calendar; // No warning here as it is suppressed by filter. HashSet hashSet; // Warning above here: Declaring variables, return values or parameters of type 'HashSet' //is not allowed. //resume ...
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> (reason)
and // CSON <ID>
, where ID is the ID of checks you want to suppress.
Examples of Checkstyle checks configuration:
<module name="RegexpSinglelineJava"> <property name="id" value="ignore"/> <property name="format" value="^.*@Ignore\s*$"/> <property name="message" value="@Ignore should have a reason."/> </module> <module name="RegexpSinglelineJava"> <property name="id" value="systemout"/> <property name="format" value="^.*System\.(out|err).*$"/> <property name="message" value="Don't use System.out/err, use SLF4J instead."/> </module>
Example of SuppressionCommentFilter configuration (checkFormat which is set to '$1' points that ID of the checks is in the first group of offCommentFormat and onCommentFormat regular expressions):
<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="CSOFF (\w+) \(\w+\)"/> <property name="onCommentFormat" value="CSON (\w+)"/> <property name="idFormat" value="$1"/> </module>
// CSOFF ignore (test has not been implemented yet) @Ignore // should NOT fail RegexpSinglelineJava @Test public void testMethod() { } // CSON ignore // CSOFF systemout (debug) public static void foo() { System.out.println("Debug info."); // should NOT fail RegexpSinglelineJava } // CSON systemout
Example of how to configure the check to suppress more than one checks.
<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="@cs-\: ([\w\|]+)"/> <property name="checkFormat" value="$1"/> </module>
// @cs-: ClassDataAbstractionCoupling // @cs-: MagicNumber @Service // no violations from ClassDataAbstractionCoupling here @Transactional public class UserService { private int value = 10022; // no violations from MagicNumber here }
Parent is com.puppycrawl.tools.checkstyle.TreeWalker
- Since:
- 3.5
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
A Tag holds a suppression comment and its location, and determines whether the suppression turns checkstyle reporting on or off.static enum
Enum to be used for switching checkstyle reporting for tags.Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
AutomaticBean.OutputStreamOptions
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate boolean
Control whether to check C style comments (/* ... */
).private boolean
Control whether to check C++ style comments (//
).private String
Specify check pattern to suppress.private static final String
Control all checks.private static final String
Turns checkstyle reporting off.private static final String
Turns checkstyle reporting on.private WeakReference
<FileContents> References the current FileContents for this filter.private String
Specify check ID pattern to suppress.private String
Specify message pattern to suppress.private Pattern
Specify comment pattern to trigger filter to begin suppression.private Pattern
Specify comment pattern to trigger filter to end suppression.private final List
<SuppressionCommentFilter.Tag> Tagged comments. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
accept
(TreeWalkerAuditEvent event) Determines whether or not a filteredTreeWalkerAuditEvent
is accepted.private void
addTag
(String text, int line, int column, SuppressionCommentFilter.TagType reportingOn) Adds aTag
to the list of all tags.private SuppressionCommentFilter.Tag
Finds the nearest comment text tag that matches an audit event.protected void
Provides a hook to finish the part of this component's setup that was not handled by the bean introspection.private FileContents
Returns FileContents for this filter.void
setCheckC
(boolean checkC) Setter to control whether to check C style comments (/* ... */
).void
setCheckCPP
(boolean checkCpp) Setter to control whether to check C++ style comments (//
).final void
setCheckFormat
(String format) Setter to specify check pattern to suppress.void
setFileContents
(FileContents fileContents) Set the FileContents for this filter.void
setIdFormat
(String format) Setter to specify check ID pattern to suppress.void
setMessageFormat
(String format) Setter to specify message pattern to suppress.final void
setOffCommentFormat
(Pattern pattern) Setter to specify comment pattern to trigger filter to begin suppression.final void
setOnCommentFormat
(Pattern pattern) Setter to specify comment pattern to trigger filter to end suppression.private void
tagCommentLine
(String text, int line, int column) Tags a string if it matches the format for turning checkstyle reporting on or the format for turning reporting off.private void
Collects all the suppression tags for all comments into a list and sorts the list.private void
tagSuppressions
(Collection<TextBlock> comments) Appends the suppressions in a collection of comments to the full set of suppression tags.Methods inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
configure, contextualize, getConfiguration, setupChild
-
Field Details
-
DEFAULT_OFF_FORMAT
Turns checkstyle reporting off.- See Also:
-
DEFAULT_ON_FORMAT
Turns checkstyle reporting on.- See Also:
-
DEFAULT_CHECK_FORMAT
Control all checks.- See Also:
-
tags
Tagged comments. -
checkC
private boolean checkCControl whether to check C style comments (/* ... */
). -
checkCPP
private boolean checkCPPControl whether to check C++ style comments (//
). -
offCommentFormat
Specify comment pattern to trigger filter to begin suppression. -
onCommentFormat
Specify comment pattern to trigger filter to end suppression. -
checkFormat
Specify check pattern to suppress. -
messageFormat
Specify message pattern to suppress. -
idFormat
Specify check ID pattern to suppress. -
fileContentsReference
References the current FileContents for this filter. Since this is a weak reference to the FileContents, the FileContents can be reclaimed as soon as the strong references in TreeWalker are reassigned to the next FileContents, at which time filtering for the current FileContents is finished.
-
-
Constructor Details
-
SuppressionCommentFilter
public SuppressionCommentFilter()
-
-
Method Details
-
setOffCommentFormat
Setter to specify comment pattern to trigger filter to begin suppression.- Parameters:
pattern
- a pattern.
-
setOnCommentFormat
Setter to specify comment pattern to trigger filter to end suppression.- Parameters:
pattern
- a pattern.
-
getFileContents
Returns FileContents for this filter.- Returns:
- the FileContents for this filter.
-
setFileContents
Set the FileContents for this filter.- Parameters:
fileContents
- the FileContents for this filter.
-
setCheckFormat
Setter to specify check pattern to suppress.- Parameters:
format
- aString
value
-
setMessageFormat
Setter to specify message pattern to suppress.- Parameters:
format
- aString
value
-
setIdFormat
Setter to specify check ID pattern to suppress.- Parameters:
format
- aString
value
-
setCheckCPP
public void setCheckCPP(boolean checkCpp) Setter to control whether to check C++ style comments (//
).- Parameters:
checkCpp
-true
if C++ comments are checked.
-
setCheckC
public void setCheckC(boolean checkC) Setter to control whether to check C style comments (/* ... */
).- Parameters:
checkC
-true
if C comments are checked.
-
finishLocalSetup
protected void finishLocalSetup()Description copied from class:AutomaticBean
Provides a hook to finish the part of this component's setup that was not handled by the bean introspection.The default implementation does nothing.
- Specified by:
finishLocalSetup
in classAutomaticBean
-
accept
Description copied from interface:TreeWalkerFilter
Determines whether or not a filteredTreeWalkerAuditEvent
is accepted.- Specified by:
accept
in interfaceTreeWalkerFilter
- Parameters:
event
- the TreeWalkerAuditEvent to filter.- Returns:
- true if the event is accepted.
-
findNearestMatch
Finds the nearest comment text tag that matches an audit event. The nearest tag is before the line and column of the event.- Parameters:
event
- theTreeWalkerAuditEvent
to match.- Returns:
- The
Tag
nearest event.
-
tagSuppressions
private void tagSuppressions()Collects all the suppression tags for all comments into a list and sorts the list. -
tagSuppressions
Appends the suppressions in a collection of comments to the full set of suppression tags.- Parameters:
comments
- the set of comments.
-
tagCommentLine
Tags a string if it matches the format for turning checkstyle reporting on or the format for turning reporting off.- Parameters:
text
- the string to tag.line
- the line number of text.column
- the column number of text.
-
addTag
private void addTag(String text, int line, int column, SuppressionCommentFilter.TagType reportingOn) Adds aTag
to the list of all tags.- Parameters:
text
- the text of the tag.line
- the line number of the tag.column
- the column number of the tag.reportingOn
-true
if the tag turns checkstyle reporting on.
-