|
1 Introduction
|
-- |
|
|
1.1 Terminology notes
|
-- |
|
|
1.2 Guide notes
|
-- |
|
|
2 Source file basics
|
↓ |
|
|
2.1 File name
|
OuterTypeFilename
(
config)
|
samples
|
|
2.2 File encoding: UTF-8
|
explanation
|
|
|
2.3 Special characters
|
↓ |
|
|
2.3.1 Whitespace characters
|
FileTabCharacter
(
config)
|
samples
|
|
2.3.2 Special escape sequences
|
IllegalTokenText
(
config)
Coverage is missing for Unicode and Octal values of \s .
It will be addressed at:
#17551
|
samples
|
|
2.3.3 Non-ASCII characters
|
AvoidEscapedUnicodeCharacters
(
config)
|
samples
|
|
3 Source file structure
|
EmptyLineSeparator
(
config)
Rule is not enforced in package-info.java file.
It will be addressed at:
#17541
Rule for module-info.java file is not covered because
of lack of support for Java modules Grammar, see details at:
#8240
|
samples
|
|
3.1 License or copyright information, if present
|
-- |
|
|
3.2 Package statement
|
LineLength
(
config)
NoLineWrap
(
config)
|
samples
|
|
3.3 Import statements
|
↓ |
|
|
3.3.1 No wildcard imports
|
AvoidStarImport
(
config)
|
samples
|
|
3.3.2 No line-wrapping
|
LineLength
(
config)
NoLineWrap
(
config)
|
samples
|
|
3.3.3 Ordering and spacing
|
CustomImportOrder
(
config)
|
samples
|
|
3.3.4 No static import for classes
|
Violations of this guideline cannot be detected by Checkstyle due to its
limitation, multiple file checking is not supported.
|
|
|
3.4 Class declaration
|
↓ |
|
|
3.4.1 Exactly one top-level class declaration
|
OneTopLevelClass
(
config)
|
samples
|
|
3.4.2 Class member ordering
|
-- |
|
|
3.4.2.1 Overloads: never split
|
OverloadMethodsDeclarationOrder
(
config)
ConstructorsDeclarationGrouping
(
config)
|
samples
|
|
3.5 Module declaration
|
↓ |
|
|
3.5.1 Ordering and spacing of module directives
|
Checkstyle currently does not have a Parser to support
module-info.java file Grammar. For more information,
see the discussion at:
#17170
|
|
|
4 Formatting
|
-- |
|
|
4.1 Braces
|
↓ |
|
|
4.1.1 Use of optional braces
|
NeedBraces
(
config)
|
samples
|
|
4.1.2 Nonempty blocks: K & R style
|
LeftCurly
(
config)
RightCurly
(
config)
There are some false-negatives regarding ELSE &
CATCH & DEFAULT blocks, they will be addressed at:
#15791
and
#15792
and
#14782
|
samples
|
|
4.1.3 Empty blocks: may be concise
|
RegexpSinglelineJava
(
config)
There are some false-negatives regarding K & R style brackets
for empty blocks, they're addressed at:
#15791
and
#15792
|
samples
|
|
4.2 Block indentation: +2 spaces
|
Indentation
(
config)
Indentation violation for separate Code Blocks are suppressed, see
#15769 for more details.
|
samples
|
|
4.3 One statement per line
|
OneStatementPerLine
(
config)
|
samples
|
|
4.4 Column limit: 100
|
LineLength
(
config)
We can detect URL with protocol type as http://, https:// etc.
JSNI
is not supported, see reason at:
#14938.
To suppress this rule for longer identifiers, please use
SuppressWithNearbyTextFilter
.
Check out Suppressions
section to learn how to use this suppression.
|
samples
|
|
4.5 Line-wrapping
|
-- |
|
|
4.5.1 Where to break
|
OperatorWrap
(
config)
SeparatorWrap
(
config)
MethodParamPad
(
config)
Line break before and after the lambda(-> ) is not covered.
It will be addressed at:
#17253
|
samples
|
|
4.5.2 Indent continuation lines at least +4 spaces
|
Indentation
(
config)
|
samples
|
|
4.6 Whitespace
|
↓ |
|
|
4.6.1 Vertical Whitespace
|
EmptyLineSeparator
(
config)
Blank lines between two consecutive fields are optional.
This exception is not satisfied
|
samples
|
|
4.6.2 Horizontal whitespace
|
WhitespaceAround
(
config)
GenericWhitespace
(
config)
MethodParamPad
(
config)
ParenPad
(
config)
WhitespaceAfter
(
config)
NoWhitespaceBefore
(
config)
NoWhitespaceBeforeCaseDefaultColon
(
config)
MatchXpath
(
config)
A whitespace is not enforced between a type annotation and []
or ... . It will be addressed at:
#15791
|
samples
|
|
4.6.3 Horizontal alignment: never required
|
-- |
|
|
4.7 Grouping parentheses: recommended
|
-- |
|
|
4.8 Specific constructs
|
↓ |
|
|
4.8.1 Enum classes
|
-- |
|
|
4.8.2 Variable declarations
|
↓ |
|
|
4.8.2.1 One variable per declaration
|
MultipleVariableDeclarations
(
config)
|
samples
|
|
4.8.2.2 Declared when needed
|
VariableDeclarationUsageDistance
(
config)
|
samples
|
|
4.8.3 Arrays
|
↓ |
|
|
4.8.3.1 Array initializers: can be "block-like"
|
-- |
|
|
4.8.3.2 No C-style array declarations
|
ArrayTypeStyle
(
config)
|
samples
|
|
4.8.4 Switch statements and expressions
|
-- |
|
|
4.8.4.1 Indentation
|
Indentation
(
config)
Line break after { of non-empty block in switch-rule is
not covered. It will be addressed at:
#17565
|
samples
|
|
4.8.4.2 Fall-through: commented
|
FallThrough
(
config)
|
samples
|
|
4.8.4.3 Exhaustiveness and presence of the default label
|
MissingSwitchDefault
(
config)
"Exception: enum type may omit the default statement group"
requirement can not be covered as we can not distinguish types,
enum values may look the same as static final String constants.
|
samples
|
|
4.8.4.4 Switch expressions
|
-- |
|
|
4.8.5 Annotations
|
↓ |
|
|
4.8.5.1 Type-use annotations
|
Violations of this guideline cannot be detected by Checkstyle due to its
limitation, multiple file checking is not supported.
|
|
|
4.8.5.2 Class, package, and module annotations
|
AnnotationLocation
(
config)
InvalidJavadocPosition
(
config)
Annotation rule for modules is not covered because of lack of support for
Java modules Grammar, see details at:
#8240
|
samples
|
|
4.8.5.3 Methods And Constructors Annotations
|
AnnotationLocation
(
config)
InvalidJavadocPosition
(
config)
|
samples
|
|
4.8.5.4 Field Annotations
|
AnnotationLocation
(
config)
InvalidJavadocPosition
(
config)
|
samples
|
|
4.8.5.5 Parameter and local variable annotations
|
--
For type-use annotations see
4.8.5.1 Type-use annotations
|
|
|
4.8.6 Comments
|
↓ |
|
|
4.8.6.1 Block comment style
|
CommentsIndentation
(
config)
|
samples
|
|
|
4.8.6.2 TODO comments
|
Support for Uppercase TODO: will be addressed at:
#17501
|
|
|
4.8.7 Modifiers
|
ModifierOrder
(
config)
Rule for Modifiers on requires module directives is not covered
because of lack of support for Java modules Grammar, see details at:
#8240
|
samples
|
|
4.8.8 Numeric Literals
|
UpperEll
(
config)
|
samples
|
|
4.8.9 Text Blocks
|
Opening and closing quotes of text blocks are always on new line and
No column limit on text block content are not covered.
They will be addressed at:
#17159
and
#11867
respectively.
|
|
|
5 Naming
|
↓ |
|
|
5.1 Rules common to all identifiers
|
CatchParameterName
(
config)
All other types of identifiers are covered in special sections below
|
samples
|
|
|
5.2 Rules by identifier type
|
↓ |
|
|
5.2.1 Package and module names
|
PackageName
(
config)
Modules name validation is not covered because of lack of support for
Java modules Grammar, see details at:
#8240
|
samples
|
|
5.2.2 Class names
|
TypeName
()
config
|
samples
|
|
5.2.3 Method names
|
MethodName
(
config)
|
samples
|
|
5.2.4 Constant names
|
Every constant is a static final field, but not all static final
fields are constants - impossible to check such rule.
|
|
|
5.2.5 Non-constant field names
|
MemberName
(
config)
|
samples
|
|
5.2.6 Parameter names
|
ParameterName
()
config
CatchParameterName
(
config)
LambdaParameterName
(
config)
RecordComponentName
(
config)
|
samples
|
|
5.2.7 Local variable names
|
LocalVariableName
(
config)
PatternVariableName
(
config)
|
samples
|
|
5.2.8 Type variable names
|
MethodTypeParameterName
(
config)
ClassTypeParameterName
(
config)
InterfaceTypeParameterName
(
config)
RecordTypeParameterName
(
config)
|
samples
|
|
5.3 Camel case: defined
|
AbbreviationAsWordInName
(
config)
Non covered:
1. Some words are ambiguously hyphenated in the
English language. No way to distinguish "YouTubeImporter" or
"YoutubeImporter".
2. Multipart Versioning Naming convention using underscores.
For example: "guava33_4_6". It will be addressed:
#17507
|
samples
|
|
6 Programming Practices
|
↓ |
|
|
6.1 @Override: always used
|
Violations of this guideline cannot be detected by Checkstyle due to its
limitation, multiple file checking is not supported.
Coverage is missing for explicitly declared accessor method for a record
component. It will be addressed at:
#17561
|
|
|
6.2 Caught exceptions: not ignored
|
EmptyCatchBlock
(
config)
Proper way of ignoring the exception will be discussed and addressed at:
#17563
|
samples
|
|
6.3 Static members: qualified using class
|
Violations of this guideline cannot be detected by Checkstyle due to its
limitation, multiple file checking is not supported.
|
|
|
6.4 Finalizers: not used
|
NoFinalizer
(
config)
|
samples
|
|
7 Javadoc
|
↓ |
|
|
7.1 Formatting
|
↓ |
|
|
7.1.1 General form
|
SingleLineJavadoc
(
config)
InvalidJavadocPosition
(
config)
|
samples
|
|
7.1.2 Paragraphs
|
JavadocParagraph
(
config)
RequireEmptyLineBeforeBlockTagGroup
(
config)
|
samples
|
|
7.1.3 Block tags
|
AtclauseOrder
(
config)
JavadocTagContinuationIndentation
(
config)
NonEmptyAtclauseDescription
(
config)
|
samples
|
|
7.2 The summary fragment
|
SummaryJavadoc
(
config)
|
samples
|
|
7.3 Where Javadoc is used
|
MissingJavadocType
(
config)
MissingJavadocMethod
(
config)
JavadocMethod
(
config)
|
samples
|
|
7.3.1 Exception: self-explanatory members
|
MissingJavadocMethod
(
config)
Optional javadoc for "simple, obvious" members is only valid for
getters/setters, but they should follow
certain rules mentioned at Check's
Description
section.
JavadocMethod
(
config)
|
samples
|
|
7.3.2 Exception: overrides
|
MissingJavadocMethod
(
config)
Overrides are checked by presence of "@Override" annotation on
method.
JavadocMethod
(
config)
|
samples
|
|
7.3.4 Non-required Javadoc
|
InvalidJavadocPosition
(
config)
|
samples
|