diff --git a/.circleci/config.yml b/.circleci/config.yml index cb1a64a..0dcd308 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -25,13 +25,12 @@ jobs: circleci step halt fi - run: make image - - run: echo "$GCR_JSON_KEY" | docker login -u _json_key --password-stdin us.gcr.io + - run: echo "$DOCKER_PASSWORD" | docker login -u "$DOCKER_USERNAME" --password-stdin - run: - name: Push image to GCR + name: Push image to Dockerhub command: | - docker tag codeclimate/codeclimate-checkstyle \ - us.gcr.io/code-climate/codeclimate-checkstyle:b$CIRCLE_BUILD_NUM - docker push us.gcr.io/code-climate/codeclimate-checkstyle:b$CIRCLE_BUILD_NUM + make release RELEASE_TAG="b$CIRCLE_BUILD_NUM" + make release RELEASE_TAG="$(echo $CIRCLE_BRANCH | grep -oP 'channel/\K[\w\-]+')" workflows: version: 2 @@ -39,6 +38,7 @@ workflows: jobs: - test - release_images: + context: Quality requires: - test filters: diff --git a/CHECKSTYLE_VERSION b/CHECKSTYLE_VERSION index 1a2c355..803ed03 100644 --- a/CHECKSTYLE_VERSION +++ b/CHECKSTYLE_VERSION @@ -1 +1 @@ -9.2 +8.39 diff --git a/Dockerfile b/Dockerfile index 6ffb154..1be881b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,7 +2,7 @@ FROM ruby:2.6.3-alpine ENV LANG C.UTF-8 -LABEL org.opencontainers.image.authors="Code Climate " +MAINTAINER "Code Climate " RUN adduser -u 9000 -D app @@ -19,7 +19,7 @@ RUN { \ ENV JAVA_HOME /usr/lib/jvm/java-1.8-openjdk/jre ENV PATH $PATH:/usr/lib/jvm/java-1.8-openjdk/jre/bin:/usr/lib/jvm/java-1.8-openjdk/bin -ENV JAVA_VERSION 8u275 +ENV JAVA_VERSION 8u252 ENV JAVA_ALPINE_VERSION 8.275.01-r0 RUN set -x \ diff --git a/Makefile b/Makefile index 2cd94bb..4456deb 100644 --- a/Makefile +++ b/Makefile @@ -1,8 +1,13 @@ -.PHONY: image test +.PHONY: image test release IMAGE_NAME ?= codeclimate/codeclimate-checkstyle +RELEASE_REGISTRY ?= codeclimate DOCKER_RUN_MOUNTED = docker run --rm --user=root -w /usr/src/app -v $(PWD):/usr/src/app +ifndef RELEASE_TAG +override RELEASE_TAG = latest +endif + image: docker build --rm -t $(IMAGE_NAME) . @@ -15,3 +20,7 @@ test: image upgrade: $(DOCKER_RUN_MOUNTED) $(IMAGE_NAME) ./bin/upgrade.sh $(DOCKER_RUN_MOUNTED) $(IMAGE_NAME) ./bin/scrape-docs + +release: + docker tag $(IMAGE_NAME) $(RELEASE_REGISTRY)/codeclimate-checkstyle:$(RELEASE_TAG) + docker push $(RELEASE_REGISTRY)/codeclimate-checkstyle:$(RELEASE_TAG) diff --git a/bin/install-checkstyle.sh b/bin/install-checkstyle.sh index 41b1ff5..7f8b316 100755 --- a/bin/install-checkstyle.sh +++ b/bin/install-checkstyle.sh @@ -1,7 +1,7 @@ #!/bin/sh # use `make upgrade` to update this URL to the latest version -URL='https://github.com/checkstyle/checkstyle/releases/download/checkstyle-9.2/checkstyle-9.2-all.jar' +URL='https://github.com/checkstyle/checkstyle/releases/download/checkstyle-8.39/checkstyle-8.39-all.jar' wget -O /usr/local/bin/checkstyle.jar $URL diff --git a/check_contents.yml b/check_contents.yml index 16cf9cb..84d24b0 100644 --- a/check_contents.yml +++ b/check_contents.yml @@ -49,7 +49,7 @@ com.puppycrawl.tools.checkstyle.checks.SuppressWarningsHolderCheck: Package: com.puppycrawl.tools.checkstyle.checks com.puppycrawl.tools.checkstyle.checks.blocks.AvoidNestedBlocksCheck: Description: | -

Finds nested blocks (blocks that are used freely in the code).

Rationale: Nested blocks are often leftovers from thedebugging process, they confuse the reader.

For example, this check finds the obsolete braces in

public void guessTheOutput()
{
int whichIsWhich = 0;
{
whichIsWhich = 2;
}
System.out.println("value = " + whichIsWhich);
}

and debugging / refactoring leftovers such as

// if (conditionThatIsNotUsedAnyLonger)
{
System.out.println("unconditional");
}

A case in a switch statement does not implicitly form a block.Thus to be able to introduce local variables that have casescope it is necessary to open a nested block. This issupported, set the allowInSwitchCase property to true andinclude all statements of the case in the block.

Finds nested blocks (blocks that are used freely in the code).

Rationale: Nested blocks are often leftovers from thedebugging process, they confuse the reader.

For example this Check finds the obsolete braces in

public void guessTheOutput()
{
int whichIsWhich = 0;
{
whichIsWhich = 2;
}
System.out.println("value = " + whichIsWhich);
}

and debugging / refactoring leftovers such as

// if (conditionThatIsNotUsedAnyLonger)
{
System.out.println("unconditional");
}

switch (a)
{
case 0:
// Never OK, break outside block
{
x = 1;
}
break;
case 1:
// Never OK, statement outside block
System.out.println("Hello");
{
x = 2;
break;
}
case 2:
// OK if allowInSwitchCase is true
{
System.out.println("Hello");
x = 3;
break;
}
}

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.blocks @@ -91,7 +91,7 @@ com.puppycrawl.tools.checkstyle.checks.coding.ArrayTrailingCommaCheck: Package: com.puppycrawl.tools.checkstyle.checks.coding com.puppycrawl.tools.checkstyle.checks.coding.AvoidDoubleBraceInitializationCheck: Description: | -

Detects double brace initialization.

Rationale: Double brace initialization (set ofInstance Initializers in class body) may look cool,but it is considered as anti-pattern and should be avoided.This is also can lead to a hard-to-detect memory leak, if the anonymous class instance isreturned outside and other object(s) hold reference to it.Created anonymous class is not static, it holds an implicit reference to the outer classinstance.See thisblog post andarticle for more details.Check ignores any comments and semicolons in class body.

Detects double brace initialization.

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.coding @@ -217,7 +217,7 @@ com.puppycrawl.tools.checkstyle.checks.coding.MagicNumberCheck: Package: com.puppycrawl.tools.checkstyle.checks.coding com.puppycrawl.tools.checkstyle.checks.coding.MatchXpathCheck: Description: | -

Evaluates Xpath query and report violation on all matching AST nodes. This check allowsuser to implement custom checks using Xpath. If Xpath query is not specified explicitly,then the check does nothing.

It is recommended to define custom message for violation to explain what is not allowedand what to use instead, default message might be too abstract. To customize a messageyou need to add message element with matchxpath.match askey attribute and desired message as value attribute.

Please read more about Xpath syntax atXpath Syntax.Information regarding Xpath functions can be found atXSLT/XPathReference. Note, that @text attribute can used only with token types thatare listed inXpathUtil.

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.coding @@ -235,7 +235,7 @@ com.puppycrawl.tools.checkstyle.checks.coding.MissingSwitchDefaultCheck: Package: com.puppycrawl.tools.checkstyle.checks.coding com.puppycrawl.tools.checkstyle.checks.coding.ModifiedControlVariableCheck: Description: | -

Checks that for loop control variables are not modified insidethe for block. An example is:

for (int i = 0; i < 1; i++) {
i++; // violation
}

Rationale: If the control variable is modified inside the loopbody, the program flow becomes more difficult to follow. SeeFOR statement specification for more details.

Such loop would be suppressed:

for (int i = 0; i < 10;) {
i++;
}

NOTE:The check works with only primitive type variables.The check will not work for arrays used as control variable.An example is

for (int a[]={0};a[0] < 10;a[0]++) {
a[0]++; // it will skip this violation
}

Checks that for loop control variables are not modified insidethe for block. An example is:

for (int i = 0; i < 1; i++) {
i++; //violation
}

Rationale: If the control variable is modified inside the loopbody, the program flow becomes more difficult to follow. SeeFOR statement specification for more details.

Such loop would be suppressed:

for (int i = 0; i < 10;) {
i++;
}

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.coding @@ -343,7 +343,7 @@ com.puppycrawl.tools.checkstyle.checks.coding.SimplifyBooleanReturnCheck: Package: com.puppycrawl.tools.checkstyle.checks.coding com.puppycrawl.tools.checkstyle.checks.coding.StringLiteralEqualityCheck: Description: | -

Checks that string literals are not used with == or!=.Since == will compare the object references,not the actual value of the strings,String.equals() should be used.More information can be foundin this article.

Rationale: Novice Java programmers often use code like:

if (x == "something")

when they mean

if ("something".equals(x))

Rationale: Novice Java programmers often use code like:

if (x == "something")

when they mean

if ("something".equals(x))

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.coding @@ -361,7 +361,7 @@ com.puppycrawl.tools.checkstyle.checks.coding.SuperFinalizeCheck: Package: com.puppycrawl.tools.checkstyle.checks.coding com.puppycrawl.tools.checkstyle.checks.coding.UnnecessaryParenthesesCheck: Description: | -

Checks if unnecessary parentheses are used in a statement or expression.The check will flag the following with warnings:

return (x); // parens around identifier
return (x + 1); // parens around return value
int x = (y / 2 + 1); // parens around assignment rhs
for (int i = (0); i < 10; i++) { // parens around literal
t -= (z + 1); // parens around assignment rhs
boolean a = (x > 7 && y > 5) // parens around expression
|| z < 9;
boolean b = (~a) > -27 // parens around ~a
&& (a-- < 30); // parens around expression

Checks if unnecessary parentheses are used in a statement or expression.The check will flag the following with warnings:

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.coding @@ -391,7 +391,7 @@ com.puppycrawl.tools.checkstyle.checks.coding.UnnecessarySemicolonInTryWithResou Package: com.puppycrawl.tools.checkstyle.checks.coding com.puppycrawl.tools.checkstyle.checks.coding.VariableDeclarationUsageDistanceCheck: Description: | -

Checks the distance between declaration of variable and its first usage.Note : Variable declaration/initialization statements are not countedwhile calculating length.

Checks the distance between declaration of variable and its first usage.

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.coding @@ -427,7 +427,7 @@ com.puppycrawl.tools.checkstyle.checks.design.InterfaceIsTypeCheck: Package: com.puppycrawl.tools.checkstyle.checks.design com.puppycrawl.tools.checkstyle.checks.design.MutableExceptionCheck: Description: | -

Ensures that exception classes (classes with names conforming to some patternand explicitly extending classes with names conforming to otherpattern) are immutable, that is, that they have only final fields.

The current algorithm is very simple: it checks that all members ofexception are final. The user can still mutate an exception's instance(e.g. Throwable has a method called setStackTracewhich changes the exception's stack trace). But, at least, all informationprovided by this exception type is unchangeable.

Rationale: Exception instances should represent an errorcondition. Having non final fields not only allows the state to bemodified by accident and therefore mask the original condition butalso allows developers to accidentally forget to set the initial state.In both cases, code catching the exception could draw incorrectconclusions based on the state.

Ensures that exception classes (classes with names conforming to some regularexpression and explicitly extending classes with names conforming to otherregular expression) are immutable, that is, that they have only final fields.

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.design @@ -481,7 +481,7 @@ com.puppycrawl.tools.checkstyle.filters.SuppressionSingleFilterCheck: Package: com.puppycrawl.tools.checkstyle.filters com.puppycrawl.tools.checkstyle.filters.SuppressionXpathFilterCheck: Description: | -

Filter SuppressionXpathFilter works asSuppressionFilter.Additionally, filter processes suppress-xpath elements,which contains xpath-expressions. Xpath-expressionsare queries for suppressed nodes inside the AST tree.

Currently, filter does not support the following checks:

NoCodeInFile (reason is that AST is not generated for a file not containing code)
Regexp (reason is at #7759)
RegexpSinglelineJava (reason is at #7759)

Also, the filter does not support suppressions inside javadoc reported by Javadoc checks:

AtclauseOrder
JavadocBlockTagLocation
JavadocMethod
JavadocMissingLeadingAsterisk
JavadocMissingWhitespaceAfterAsterisk
JavadocParagraph
JavadocStyle
JavadocTagContinuationIndentation
JavadocType
MissingDeprecated
NonEmptyAtclauseDescription
RequireEmptyLineBeforeBlockTagGroup
SingleLineJavadoc
SummaryJavadoc
WriteTag

Note, that support for these Checks will be available after resolving issue#5770.

Currently, filter supports the followingxpath axes:

ancestor
ancestor-or-self
attribute
child
descendant
descendant-or-self
following
following-sibling
parent
preceding
preceding-sibling
self

You can use the command line helper tool to generate xpathsuppressions based on your configuration file and input files.Seeherefor more details.

Currently, filter does not support the following checks:

NoCodeInFile (reason is that AST is not generated for a file not containing code)
Regexp (reason is at #7759)
RegexpSinglelineJava (reason is at #7759)

Also, the filter does not support suppressions inside javadoc reported by Javadoc checks:

AtclauseOrder
JavadocBlockTagLocation
JavadocMethod
JavadocMissingLeadingAsterisk
JavadocMissingWhitespaceAfterAsterisk
JavadocParagraph
JavadocStyle
JavadocTagContinuationIndentation
JavadocType
MissingDeprecated
NonEmptyAtclauseDescription
RequireEmptyLineBeforeBlockTagGroup
SingleLineJavadoc
SummaryJavadoc
WriteTag

Note, that support for these Checks will be available after resolving issues#5770 and#5777.

Currently, filter supports the followingxpath axes:

ancestor
ancestor-or-self
attribute
child
descendant
descendant-or-self
following
following-sibling
parent
preceding
preceding-sibling
self

You can use the command line helper tool to generate xpathsuppressions based on your configuration file and input files.Seeherefor more details.

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.filters @@ -517,7 +517,7 @@ com.puppycrawl.tools.checkstyle.checks.header.HeaderCheck: Package: com.puppycrawl.tools.checkstyle.checks.header com.puppycrawl.tools.checkstyle.checks.header.RegexpHeaderCheck: Description: | -

Checks the header of a source file against a header that contains apattern for each line of the source header.

Rationale: In some projects checking against afixed header is not sufficient, e.g. the header might require acopyright line where the year information is not static.

For example, consider the following header:

line 1: ^/{71}$
line 2: ^// checkstyle:$
line 3: ^// Checks Java source code for adherence to a set of rules\.$
line 4: ^// Copyright $C$ \d\d\d\d Oliver Burn$
line 5: ^// Last modification by \$Author.*\$$
line 6: ^/{71}$
line 7:
line 8: ^package
line 9:
line 10: ^import
line 11:
line 12: ^/\*\*
line 13: ^ \*([^/]|$)
line 14: ^ \*/

Lines 1 and 6 demonstrate a more compact notation for 71 '/'characters. Line 4 enforces that the copyright notice includes afour digit year. Line 5 is an example how to enforce revisioncontrol keywords in a file header. Lines 12-14 is a template forjavadoc (line 13 is so complicated to remove conflict with and ofjavadoc comment). Lines 7, 9 and 11 will be treated as '^$' andwill forcefully expect the line to be empty.

Different programming languages have different comment syntaxrules, but all of them start a comment with a non-wordcharacter. Hence you can often use the non-word characterclass to abstract away the concrete comment syntax and allowchecking the header for different languages with a singleheader definition. For example, consider the following headerspecification (note that this is not the full Apache licenseheader):

line 1: ^#!
line 2: ^<\?xml.*>$
line 3: ^\W*$
line 4: ^\W*Copyright 2006 The Apache Software Foundation or its licensors, as applicable\.$
line 5: ^\W*Licensed under the Apache License, Version 2\.0 $the "License"$;$
line 6: ^\W*$

Lines 1 and 2 leave room for technical header lines, e.g. the"#!/bin/sh" line in Unix shell scripts, or the XML file headerof XML files. Set the multiline property to "1, 2" so theselines can be ignored for file types where they do no apply.Lines 3 through 6 define the actual header content. Note howlines 2, 4 and 5 use escapes for characters that have specialregexp semantics.

In default configuration, if header is not specified, the default valueof header is set to null and the check does not rise any violations.

Checks the header of a source file against a header that contains aregular expression for each line of the source header.

Rationale: In some projects checking against afixed header is not sufficient, e.g. the header might require acopyright line where the year information is not static.

For example, consider the following header:

In default configuration, if header is not specified, the default valueof header is set to null and the check does not rise any violations.

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.header @@ -595,7 +595,7 @@ com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocContentLocationCheck: Package: com.puppycrawl.tools.checkstyle.checks.javadoc com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocMethodCheck: Description: | -

Checks the Javadoc of a method or constructor.

Violates parameters and type parametersfor which no param tags arepresent can be suppressed by defining propertyallowMissingParamTags.

Violates methods which return non-void but for which no return tag ispresent can be suppressed by defining propertyallowMissingReturnTag.

Violates exceptions which are declared to be thrown (by throws in the methodsignature or by throw new in the method body), but for which no throws tag ispresent by activation of property validateThrows.Note that throw new is not checked in the following places:

Inside a try block (with catch). It is not possible to determine if the thrownexception can be caught by the catch block as there is no knowledge of theinheritance hierarchy, so the try block is ignored entirely. However, catchand finally blocks, as well as try blocks without catch, are still checked.
Local classes, anonymous classes and lambda expressions. It is not known when thethrow statements inside such classes are going to be evaluated, so they are ignored.

ATTENTION: Checkstyle does not have information about hierarchy of exception typesso usage of base class is considered as separate exception type.As workaround you need to specify both types in javadoc (parent and exact type).

Javadoc is not required on a method that is tagged with the@Override annotation. However underJava 5 it is not possible to mark a method required for aninterface (this was corrected under Java 6). HenceCheckstyle supports using the convention of using a single{@inheritDoc} tag instead of all theother tags.

Note that only inheritable items will allow the{@inheritDoc} tag to be used in placeof comments. Static methods at all visibilities, private non-staticmethods and constructors are not inheritable.

For example, if the following method isimplementing a method required by an interface, then theJavadoc could be done as:

/** {@inheritDoc} */
public int checkReturnTag(final int aTagIndex,
JavadocTag[] aTags,
int aLineNo)

Checks the Javadoc of a method or constructor. The scopeto verify is specified using the Scope class anddefaults to Scope.PRIVATE. To verify anotherscope, set property scope to a differentscope.

Violates parameters and type parametersfor which no param tags arepresent can be suppressed by defining propertyallowMissingParamTags.

Violates methods which return non-void but for which no return tag ispresent can be suppressed by defining propertyallowMissingReturnTag.

Inside a try block (with catch). It is not possible to determine if the thrownexception can be caught by the catch block as there is no knowledge of theinheritance hierarchy, so the try block is ignored entirely. However, catchand finally blocks, as well as try blocks without catch, are still checked.
Local classes, anonymous classes and lambda expressions. It is not known when thethrow statements inside such classes are going to be evaluated, so they are ignored.

Note that only inheritable items will allow the{@inheritDoc} tag to be used in placeof comments. Static methods at all visibilities, private non-staticmethods and constructors are not inheritable.

For example, if the following method isimplementing a method required by an interface, then theJavadoc could be done as:

/** {@inheritDoc} */
public int checkReturnTag(final int aTagIndex,
JavadocTag[] aTags,
int aLineNo)

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.javadoc @@ -637,7 +637,7 @@ com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTagContinuationIndentation Package: com.puppycrawl.tools.checkstyle.checks.javadoc com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTypeCheck: Description: | -

Checks the Javadoc comments for type definitions.By default, does not check for author or version tags. Thescope to verify is specified using the Scopeclass and defaults to Scope.PRIVATE. To verifyanother scope, set property scope to one of theScope constants. To define the format for anauthor tag or a version tag, set property authorFormat orversionFormat respectively to apattern.

Does not perform checks for author and version tags for innerclasses, as they should be redundant because of outer class.

Error messages about type parameters and record components for which noparam tags are present can be suppressed by defining propertyallowMissingParamTags.

Does not perform checks for author and version tags for innerclasses, as they should be redundant because of outer class.

Error messages about type parameters and record components for which noparam tags are present can be suppressed by defining propertyallowMissingParamTags.

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.javadoc @@ -649,7 +649,7 @@ com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocVariableCheck: Package: com.puppycrawl.tools.checkstyle.checks.javadoc com.puppycrawl.tools.checkstyle.checks.javadoc.MissingJavadocMethodCheck: Description: | -

Checks for missing Javadoc comments for a method or constructor.The scope to verify is specified using the Scope class anddefaults to Scope.PUBLIC. To verify anotherscope, set property scope to a differentscope.

For getters and setters for the property allowMissingPropertyJavadoc,the methods must match exactly the structures below.

public void setNumber(final int number)
{
mNumber = number;
}

public int getNumber()
{
return mNumber;
}

public boolean isSomething()
{
return false;
}

For getters and setters for the property allowMissingPropertyJavadoc,the methods must match exactly the structures below.

public void setNumber(final int number){mNumber = number;}public int getNumber(){return mNumber;}public boolean isSomething(){return false;}

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.javadoc @@ -745,7 +745,7 @@ com.puppycrawl.tools.checkstyle.checks.AvoidEscapedUnicodeCharactersCheck: Package: com.puppycrawl.tools.checkstyle.checks com.puppycrawl.tools.checkstyle.checks.indentation.CommentsIndentationCheck: Description: | -

Controls the indentation between comments and surrounding code.Comments are indented at the same level as the surrounding code.Detailed info about such convention can be foundhere

Please take a look at the following examples to understand how the check works:

Example #1: Block comments.

1 /*
2 * it is Ok
3 */
4 boolean bool = true;
5
6 /* violation
7 * (block comment should have the same indentation level as line 9)
8 */
9 double d = 3.14;

Example #2: Comment is placed at the end of the block and has previous statement.

1 public void foo1() {
2 foo2();
3 // it is OK
4 }
5
6 public void foo2() {
7 foo3();
8 // violation (comment should have the same indentation level as line 7)
9 }

Example #3: Comment is used as a single line border to separate groups of methods.

1 /////////////////////////////// it is OK
2
3 public void foo7() {
4 int a = 0;
5 }
6
7 ///////////////////////////// violation (should have the same indentation level as line 9)
8
9 public void foo8() {}

Example #4: Comment has distributed previous statement.

1 public void foo11() {
2 CheckUtil
3 .getFirstNode(new DetailAST())
4 .getFirstChild()
5 .getNextSibling();
6 // it is OK
7 }
8
9 public void foo12() {
10 CheckUtil
11 .getFirstNode(new DetailAST())
12 .getFirstChild()
13 .getNextSibling();
14 // violation (should have the same indentation level as line 10)
15 }

Example #5: Single line block comment is placed within an empty code block.Note, if comment is placed at the end of the empty code block, we have Checkstyle'slimitations to clearly detect user intention of explanation target - above or below. Theonly case we can assume as a violation is when a single line comment within the emptycode block has indentation level that is lower than the indentation level of the closingright curly brace.

1 public void foo46() {
2 // comment
3 // block
4 // it is OK (we cannot clearly detect user intention of explanation target)
5 }
6
7 public void foo46() {
8 // comment
9 // block
10 // violation (comment should have the same indentation level as line 11)
11 }

Example #6: 'fallthrough' comments and similar.

0 switch(a) {
1 case "1":
2 int k = 7;
3 // it is OK
4 case "2":
5 int k = 7;
6 // it is OK
7 case "3":
8 if (true) {}
9 // violation (should have the same indentation level as line 8 or 10)
10 case "4":
11 case "5": {
12 int a;
13 }
14 // fall through (it is OK)
15 case "12": {
16 int a;
17 }
18 default:
19 // it is OK
20 }

Example #7: Comment is placed within a distributed statement.

1 String breaks = "J"
2 // violation (comment should have the same indentation level as line 3)
3 + "A"
4 // it is OK
5 + "V"
6 + "A"
7 // it is OK
8 ;

Example #8: Comment is placed within an empty case block.Note, if comment is placed at the end of the empty case block, we have Checkstyle'slimitations to clearly detect user intention of explanation target - above or below. Theonly case we can assume as a violation is when a single line comment within the empty caseblock has indentation level that is lower than the indentation level of the next casetoken.

1 case 4:
2 // it is OK
3 case 5:
4 // violation (should have the same indentation level as line 3 or 5)
5 case 6:

Example #9: Single line block comment has previous and next statement.

1 String s1 = "Clean code!";
2 s.toString().toString().toString();
3 // single line
4 // block
5 // comment (it is OK)
6 int a = 5;
7
8 String s2 = "Code complete!";
9 s.toString().toString().toString();
10 // violation (should have the same indentation level as line 11)
11 // violation (should have the same indentation level as line 12)
12 // violation (should have the same indentation level as line 13)
13 int b = 18;

Example #10: Comment within the block tries to describe the next code block.

1 public void foo42() {
2 int a = 5;
3 if (a == 5) {
4 int b;
5 // it is OK
6 } else if (a ==6) { ... }
7 }
8
9 public void foo43() {
10 try {
11 int a;
12 // Why do we catch exception here? - violation (not the same indentation as line 11)
13 } catch (Exception e) { ... }
14 }

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.indentation @@ -793,13 +793,13 @@ com.puppycrawl.tools.checkstyle.checks.OuterTypeFilenameCheck: Package: com.puppycrawl.tools.checkstyle.checks com.puppycrawl.tools.checkstyle.checks.TodoCommentCheck: Description: | -

Checks for TODO: comments. Actuallyit is a genericpattern matcher on Java comments. To check for otherpatterns in Java comments, set the format property.

Checks for TODO: comments. Actuallyit is a genericregularexpression matcher on Java comments. To check for otherpatterns in Java comments, set the format property.

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks com.puppycrawl.tools.checkstyle.checks.TrailingCommentCheck: Description: | -

The check to ensure that lines with code do not end with comment.For the case of // comments that means that the only thingthat should precede it is whitespace. It doesn't check comments ifthey do not end a line; for example, it accepts the following:Thread.sleep( 10 /*some comment here*/ ); Formatproperty is intended to deal with the } // while example.

Rationale: Steve McConnell in Code Complete suggests thatendline comments are a bad practice. An end line comment would beone that is on the same line as actual code. For example:

a = b + c; // Some insightful comment
d = e / f; // Another comment for this line

Quoting Code Complete for the justification:

"The comments have to be aligned so that they do notinterfere with the visual structure of the code. If you don't alignthem neatly, they'll make your listing look like it's been through awashing machine."
"Endline comments tend to be hard to format...It takestime to align them. Such time is not spent learning more about thecode; it's dedicated solely to the tedious task of pressing thespacebar or tab key."
"Endline comments are also hard to maintain. If the codeon any line containing an endline comment grows, it bumps thecomment farther out, and all the other endline comments will have tobumped out to match. Styles that are hard to maintain aren'tmaintained...."
"Endline comments also tend to be cryptic. The right sideof the line doesn't offer much room and the desire to keep thecomment on one line means the comment must be short. Work then goesinto making the line as short as possible instead of as clear aspossible. The comment usually ends up as cryptic aspossible...."
"A systemic problem with endline comments is that it'shard to write a meaningful comment for one line of code. Mostendline comments just repeat the line of code, which hurts more thanit helps."

McConnell's comments on being hard to maintain when the size of the linechanges are even more important in the age of automatedrefactorings.

The check to ensure that requires that comments be the only thing ona line. For the case of // comments that means that the only thingthat should precede it is whitespace. It doesn't check comments ifthey do not end a line; for example, it accepts the following:Thread.sleep( 10 /*some comment here*/ ); Formatproperty is intended to deal with the } // while example.

Rationale: Steve McConnell in Code Complete suggests thatendline comments are a bad practice. An end line comment would beone that is on the same line as actual code. For example:

a = b + c; // Some insightful comment
d = e / f; // Another comment for this line

Quoting Code Complete for the justification:

"The comments have to be aligned so that they do notinterfere with the visual structure of the code. If you don't alignthem neatly, they'll make your listing look like it's been through awashing machine."
"Endline comments tend to be hard to format...It takestime to align them. Such time is not spent learning more about thecode; it's dedicated solely to the tedious task of pressing thespacebar or tab key."
"Endline comments are also hard to maintain. If the codeon any line containing an endline comment grows, it bumps thecomment farther out, and all the other endline comments will have tobumped out to match. Styles that are hard to maintain aren'tmaintained...."
"Endline comments also tend to be cryptic. The right sideof the line doesn't offer much room and the desire to keep thecomment on one line means the comment must be short. Work then goesinto making the line as short as possible instead of as clear aspossible. The comment usually ends up as cryptic aspossible...."
"A systemic problem with endline comments is that it'shard to write a meaningful comment for one line of code. Mostendline comments just repeat the line of code, which hurts more thanit helps."

McConnell's comments on being hard to maintain when the size of the linechanges are even more important in the age of automatedrefactorings.

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks @@ -841,7 +841,7 @@ com.puppycrawl.tools.checkstyle.checks.modifier.InterfaceMemberImpliedModifierCh Package: com.puppycrawl.tools.checkstyle.checks.modifier com.puppycrawl.tools.checkstyle.checks.modifier.ModifierOrderCheck: Description: | -

Checks that the order of modifiers conforms to the suggestions inthe JavaLanguage specification, § 8.1.1, 8.3.1, 8.4.3 and9.4. The correct order is:

public
protected
private
abstract
default
static
sealed
non-sealed
final
transient
volatile
synchronized
native
strictfp

In additional, modifiers are checked to ensure all annotations aredeclared before all other modifiers.

Rationale: Code is easier to read if everybody follows a standard.

ATTENTION: We skiptype annotations from validation.

Checks that the order of modifiers conforms to the suggestions inthe JavaLanguage specification, § 8.1.1, 8.3.1, 8.4.3 and9.4. The correct order is:

public
protected
private
abstract
default
static
final
transient
volatile
synchronized
native
strictfp

In additional, modifiers are checked to ensure all annotations aredeclared before all other modifiers.

Rationale: Code is easier to read if everybody follows a standard.

ATTENTION: We skiptype annotations from validation.

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.modifier @@ -860,7 +860,7 @@ com.puppycrawl.tools.checkstyle.checks.naming.AbbreviationAsWordInNameCheck: Package: com.puppycrawl.tools.checkstyle.checks.naming com.puppycrawl.tools.checkstyle.checks.naming.AbstractClassNameCheck: Description: | -

Ensures that the names of abstract classes conforming to some pattern andcheck that abstract modifier exists.

Rationale: Abstract classes are convenience base class implementations ofinterfaces, not types as such. As such they should be named to indicate this.Also if names of classes starts with 'Abstract' it's very convenient thatthey will have abstract modifier.

Ensures that the names of abstract classes conforming to some regular expression andcheck that abstract modifier exists.

This documentation is written and maintained by the Checkstyle community and is covered under the same license as the Checkstyle project.

Package: com.puppycrawl.tools.checkstyle.checks.naming @@ -884,7 +884,7 @@ com.puppycrawl.tools.checkstyle.checks.naming.ConstantNameCheck: Package: com.puppycrawl.tools.checkstyle.checks.naming "