From 371ffafdd0f5130f46b8d065dcb43d592cb756e7 Mon Sep 17 00:00:00 2001 From: Filipe Esperandio Date: Mon, 11 Nov 2019 18:30:31 -0300 Subject: [PATCH 1/2] Upgrade to 8.26 --- CHECKSTYLE_VERSION | 2 +- bin/install-checkstyle.sh | 3 ++- check_contents.yml | 42 +++++++++++++++++++-------------------- 3 files changed, 24 insertions(+), 23 deletions(-) diff --git a/CHECKSTYLE_VERSION b/CHECKSTYLE_VERSION index 01351bd..f5e5cc5 100644 --- a/CHECKSTYLE_VERSION +++ b/CHECKSTYLE_VERSION @@ -1 +1 @@ -8.25 +8.26 diff --git a/bin/install-checkstyle.sh b/bin/install-checkstyle.sh index c824641..6867acc 100755 --- a/bin/install-checkstyle.sh +++ b/bin/install-checkstyle.sh @@ -1,6 +1,7 @@ #!/bin/sh # use `make upgrade` to update this URL to the latest version -URL='https://github.com/checkstyle/checkstyle/releases/download/checkstyle-8.25/checkstyle-8.25-all.jar' +URL='https://github.com/checkstyle/checkstyle/releases/download/checkstyle-8.26/checkstyle-8.26-all.jar' + wget -O /usr/local/bin/checkstyle.jar $URL diff --git a/check_contents.yml b/check_contents.yml index 428634d..86b3396 100644 --- a/check_contents.yml +++ b/check_contents.yml @@ -475,25 +475,25 @@ com.puppycrawl.tools.checkstyle.filters.SuppressWithPlainTextCommentFilterCheck: Package: com.puppycrawl.tools.checkstyle.filters com.puppycrawl.tools.checkstyle.checks.header.HeaderCheck: Description: | -

Since Checkstyle 6.9

Checks that a source file begins with a specified header. Property headerFile specifies a file that containsthe required header. Alternatively, the header specification can beset directly in the header propertywithout the need for an external file.

Property ignoreLines specifies the linenumbers to ignore when matching lines in a header file. Thisproperty is very useful for supporting headers that containcopyright dates. For example, consider the following header:


line 1: ////////////////////////////////////////////////////////////////////
line 2: // checkstyle:
line 3: // Checks Java source code for adherence to a set of rules.
line 4: // Copyright (C) 2002 Oliver Burn
line 5: ////////////////////////////////////////////////////////////////////

Since the year information will change over time, you can tellCheckstyle to ignore line 4 by setting property ignoreLines to 4.

+

Checks that a source file begins with a specified header. PropertyheaderFile specifies a file that containsthe required header. Alternatively, the header specification can beset directly in the header propertywithout the need for an external file.

Property ignoreLines specifies the linenumbers to ignore when matching lines in a header file. Thisproperty is very useful for supporting headers that containcopyright dates. For example, consider the following header:


line 1: ////////////////////////////////////////////////////////////////////
line 2: // checkstyle:
line 3: // Checks Java source code for adherence to a set of rules.
line 4: // Copyright (C) 2002 Oliver Burn
line 5: ////////////////////////////////////////////////////////////////////

Since the year information will change over time, you can tellCheckstyle to ignore line 4 by setting property ignoreLines to4.

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 com.puppycrawl.tools.checkstyle.checks.header.RegexpHeaderCheck: Description: | -

Since Checkstyle 6.9

Checks the header of a source file against a header that contains aregularexpression 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.

+

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:


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.

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 com.puppycrawl.tools.checkstyle.checks.imports.AvoidStarImportCheck: Description: | -

Since Checkstyle 3.0

Checks that there are no import statements that use the * notation.

Rationale: Importing all classes from a package or staticmembers from a class leads to tight coupling between packagesor classes and might lead to problems when a new version of alibrary introduces name clashes.

+

Checks that there are no import statements that use the * notation.

Rationale: Importing all classes from a package or staticmembers from a class leads to tight coupling between packagesor classes and might lead to problems when a new version of alibrary introduces name clashes.

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.imports com.puppycrawl.tools.checkstyle.checks.imports.AvoidStaticImportCheck: Description: | -

Since Checkstyle 5.0

Checks that there are no static import statements.

Rationale: Importing static members can lead to namingconflicts between class' members. It may lead to poor codereadability since it may no longer be clear what class amember resides in (without looking at the import statement).

+

Checks that there are no static import statements.

Rationale: Importing static members can lead to namingconflicts between class' members. It may lead to poor codereadability since it may no longer be clear what class amember resides in (without looking at the import statement).

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.imports @@ -505,13 +505,13 @@ com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck: Package: com.puppycrawl.tools.checkstyle.checks.imports com.puppycrawl.tools.checkstyle.checks.imports.IllegalImportCheck: Description: | -

Since Checkstyle 3.0

Checks for imports from a set of illegal packages. By default, thecheck rejects all sun.* packages sinceprograms that contain direct calls to the sun.* packages are "notguaranteed to work on all Java-compatible platforms". To reject other packages,set property illegalPkgs to a list of the illegal packages.

+

Checks for imports from a set of illegal packages.

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.imports com.puppycrawl.tools.checkstyle.checks.imports.ImportControlCheck: Description: | -

Since Checkstyle 4.0

Controls what can be imported in each package and file. Useful forensuring that application layering rules are not violated,especially on large projects.

You can control imports based on the a package name or based on the filename. When controlling packages, all files and sub-packages in the declaredpackage will be controlled by this check. To specify differences between a main packageand a sub-package, you must define the sub-package inside the main package. Whencontrolling file, only the file name is considered and only files processed byTreeWalker. The file's extension is ignored.

Short description of the behaviour:

The DTD for a import control XML document is at https://checkstyle.org/dtds/import_control_1_4.dtd. Itcontains documentation on each of the elements and attributes.

The check validates a XML document when it loads the document.To validate against the above DTD, include the followingdocument type declaration in your XML document:


<!DOCTYPE import-control PUBLIC
    "-//Checkstyle//DTD ImportControl Configuration 1.4//EN"
    "https://checkstyle.org/dtds/import_control_1_4.dtd">

+

Controls what can be imported in each package and file. Useful forensuring that application layering rules are not violated,especially on large projects.

You can control imports based on the a package name or based on the filename. When controlling packages, all files and sub-packages in the declaredpackage will be controlled by this check. To specify differences between a main packageand a sub-package, you must define the sub-package inside the main package. Whencontrolling file, only the file name is considered and only files processed byTreeWalker. The file's extension is ignored.

Short description of the behaviour:

The DTD for a import control XML document is at https://checkstyle.org/dtds/import_control_1_4.dtd. Itcontains documentation on each of the elements and attributes.

The check validates a XML document when it loads the document.To validate against the above DTD, include the followingdocument type declaration in your XML document:


<!DOCTYPE import-control PUBLIC
    "-//Checkstyle//DTD ImportControl Configuration 1.4//EN"
    "https://checkstyle.org/dtds/import_control_1_4.dtd">

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.imports @@ -523,13 +523,13 @@ com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck: Package: com.puppycrawl.tools.checkstyle.checks.imports com.puppycrawl.tools.checkstyle.checks.imports.RedundantImportCheck: Description: | -

Since Checkstyle 3.0

Checks for redundant import statements. An import statement isconsidered redundant if:

+

Checks for redundant import statements. An import statement isconsidered redundant if:

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.imports com.puppycrawl.tools.checkstyle.checks.imports.UnusedImportsCheck: Description: | -

Since Checkstyle 3.0

Checks for unused import statements. Checkstyle uses a simple butvery reliable algorithm to report on unused import statements. Animport statement is considered unused if:

The main limitation of this check is handling the case wherean imported type has the same name as a declaration, such as amember variable.

For example, in the following case the import java.awt.Componentwill not be flagged as unused:


import java.awt.Component;
class FooBar {
private Object Component; // a bad practice in my opinion
...
}

+

Checks for unused import statements. Checkstyle uses a simple butvery reliable algorithm to report on unused import statements. Animport statement is considered unused if:

The main limitation of this check is handling the case wherean imported type has the same name as a declaration, such as amember variable.

For example, in the following case the import java.awt.Componentwill not be flagged as unused:


import java.awt.Component;
class FooBar {
private Object Component; // a bad practice in my opinion
...
}

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.imports @@ -637,37 +637,37 @@ com.puppycrawl.tools.checkstyle.checks.javadoc.WriteTagCheck: Package: com.puppycrawl.tools.checkstyle.checks.javadoc com.puppycrawl.tools.checkstyle.checks.metrics.BooleanExpressionComplexityCheck: Description: | -

Since Checkstyle 3.4

Restrict the number of number of &&, ||,&, |and ^ in an expression.

Rationale: Too many conditions leads to code that is difficultto read and hence debug and maintain.

Note that the operators & and| are not only integer bitwise operators, they are also thenon-shortcut versions of the boolean operators.&& and ||.

Note that &, | and ^ are not checkedif they are part of constructor or method callbecause they can be applied to non boolean variables andCheckstyle does not know types of methods from different classes.

+

Restrict the number of &&, ||,&, |and ^ in an expression.

Rationale: Too many conditions leads to code that is difficultto read and hence debug and maintain.

Note that the operators & and| are not only integer bitwise operators, they are also thenon-shortcut versions of the boolean operators&& and ||.

Note that &, | and ^ are not checkedif they are part of constructor or method callbecause they can be applied to non boolean variables andCheckstyle does not know types of methods from different classes.

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.metrics com.puppycrawl.tools.checkstyle.checks.metrics.ClassDataAbstractionCouplingCheck: Description: | -

Since Checkstyle 3.4

This metric measures the number of instantiations of otherclasses within the given class. This type of coupling is notcaused by inheritance or the object orientedparadigm. Generally speaking, any data type with other datatypes as members or local variable that is an instantiation(object) of another class has data abstraction coupling (DAC).The higher the DAC, the more complex the structure of the class.

This check processes files in the following way:

  1. Iterates over the list of tokens (defined below) and counts all mentioned classes.
  2. If a class was imported with direct import (i.e.import java.math.BigDecimal), or the class was referenced with thepackage name (i.e. java.math.BigDecimal value) and the package wasadded to the excludedPackages parameter, the class does notincrease complexity.
  3. If a class name was added to the excludedClasses parameter,the class does not increase complexity.

+

This metric measures the number of instantiations of otherclasses within the given class. This type of coupling is notcaused by inheritance or the object orientedparadigm. Generally speaking, any data type with other datatypes as members or local variable that is an instantiation(object) of another class has data abstraction coupling (DAC).The higher the DAC, the more complex the structure of the class.

This check processes files in the following way:

  1. Iterates over the list of tokens (defined below) and counts all mentioned classes.
  2. If a class was imported with direct import (i.e.import java.math.BigDecimal), or the class was referenced with thepackage name (i.e. java.math.BigDecimal value) and the package wasadded to the excludedPackages parameter, the class does notincrease complexity.
  3. If a class name was added to the excludedClasses parameter,the class does not increase complexity.

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.metrics com.puppycrawl.tools.checkstyle.checks.metrics.ClassFanOutComplexityCheck: Description: | -

Since Checkstyle 3.4

The number of other classes a given class relies on. Also thesquare of this has been shown to indicate the amount ofmaintenance required in functional programs (on a file basis)at least.

This check processes files in the following way:

  1. Iterates over all tokens that might contain type reference.
  2. If a class was imported with direct import (i.e.import java.math.BigDecimal), or the class was referenced with thepackage name (i.e. java.math.BigDecimal value) and the package wasadded to the excludedPackages parameter, the class does not increasecomplexity.
  3. If a class name was added to the excludedClasses parameter,the class does not increase complexity.

+

The number of other classes a given class relies on. Also thesquare of this has been shown to indicate the amount ofmaintenance required in functional programs (on a file basis)at least.

This check processes files in the following way:

  1. Iterates over all tokens that might contain type reference.
  2. If a class was imported with direct import (i.e.import java.math.BigDecimal), or the class was referenced with thepackage name (i.e. java.math.BigDecimal value) and the package wasadded to the excludedPackages parameter, the class does not increasecomplexity.
  3. If a class name was added to the excludedClasses parameter,the class does not increase complexity.

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.metrics com.puppycrawl.tools.checkstyle.checks.metrics.CyclomaticComplexityCheck: Description: | -

Since Checkstyle 3.2

Checks cyclomatic complexity against a specified limit.It is a measure of the minimum number ofpossible paths through the source and therefore the number ofrequired tests, it is not a about quality of code!It is only applied to methods, c-tors,static initializers and instance initializers.

The complexity is equal to the number of decision points + 1Decision points: if, while, do, for, ?:, catch, switch, casestatements, and operators && and ||in the body of target.

By pure theory level 1-4 is considered easy to test, 5-7 OK, 8-10consider re-factoring to ease testing, and 11+ re-factor now as testing will be painful.

When it comes to code quality measurement by this metriclevel 10 is very good level as a ultimate target (that is hard to archive).Do not be ashamed to have complexity level 15 or even higher,but keep it below 20 to catch really bad designed code automatically.

Please use Suppression to avoid violations on cases that could not be split in fewmethods without damaging readability of code or encapsulation.

+

Checks cyclomatic complexity against a specified limit.It is a measure of the minimum number ofpossible paths through the source and therefore the number ofrequired tests, it is not a about quality of code!It is only applied to methods, c-tors,static initializers and instance initializers.

The complexity is equal to the number of decision points + 1.Decision points: if, while, do, for, ?:, catch, switch, casestatements and operators && and ||in the body of target.

By pure theory level 1-4 is considered easy to test, 5-7 OK, 8-10consider re-factoring to ease testing, and 11+ re-factor now as testing will be painful.

When it comes to code quality measurement by this metriclevel 10 is very good level as a ultimate target (that is hard to archive).Do not be ashamed to have complexity level 15 or even higher,but keep it below 20 to catch really bad designed code automatically.

Please use Suppression to avoid violations on cases that could not be split in fewmethods without damaging readability of code or encapsulation.

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.metrics com.puppycrawl.tools.checkstyle.checks.metrics.JavaNCSSCheck: Description: | -

Since Checkstyle 3.5

Determines complexity of methods, classes and files bycounting the Non Commenting Source Statements (NCSS). Thischeck adheres to the specification for theJavaNCSS-Toolwritten by Chr. Clemens Lee.

Roughly said the NCSS metric is calculated bycounting the source lines which are not comments, (nearly)equivalent to counting the semicolons and opening curlybraces.

The NCSS for a class is summarized from the NCSSof all its methods, the NCSS of its nested classes and thenumber of member variable declarations.

The NCSS for afile is summarized from the ncss of all its top level classes,the number of imports and the package declaration.

Rationale: Too large methods and classes are hard to read andcostly to maintain. A large NCSS number often means that amethod or class has too many responsibilities and/orfunctionalities which should be decomposed into smaller units.

+

Determines complexity of methods, classes and files bycounting the Non Commenting Source Statements (NCSS). Thischeck adheres to the specification for theJavaNCSS-Toolwritten by Chr. Clemens Lee.

Roughly said the NCSS metric is calculated bycounting the source lines which are not comments, (nearly)equivalent to counting the semicolons and opening curly braces.

The NCSS for a class is summarized from the NCSSof all its methods, the NCSS of its nested classes and thenumber of member variable declarations.

The NCSS for a file is summarized from the ncss of all its top level classes,the number of imports and the package declaration.

Rationale: Too large methods and classes are hard to read andcostly to maintain. A large NCSS number often means that amethod or class has too many responsibilities and/orfunctionalities which should be decomposed into smaller units.

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.metrics com.puppycrawl.tools.checkstyle.checks.metrics.NPathComplexityCheck: Description: | -

Since Checkstyle 3.4

The NPATH metric computes the number of possible executionpaths through a function(method). It takes into account the nesting ofconditional statements and multi-part boolean expressions(A && B, C || D, E ? F :G and their combinations).

The NPATH metric was designed base on Cyclomatic complexity toavoid problem of Cyclomatic complexity metric like nesting level within afunction(method).

Metric was described at "NPATH: a measure of execution pathcomplexity and its applications". If you need detailed description of algorithm, please read that article,it is well written and have number of examples and details.

Here is some quotes:

An NPATH threshold value of 200 has been establishedfor a function. The value 200 is based on studies doneat AT&T Bell Laboratories [1988 year].
Some of the most effective methods of reducing the NPATH value include

- distributing functionality,

- implementing multiple if statements as a switch statement

- creating a separate function for logical expressions with a high count ofand (&&) and or (||) operators.
Although strategies to reduce the NPATH complexityof functions are important, care must be taken not todistort the logical clarity of the software by applying astrategy to reduce the complexity of functions. That is,there is a point of diminishing return beyond which afurther attempt at reduction of complexity distorts thelogical clarity of the system structure.
Structure Complexity expression
if ([expr]) { [if-range] }NP(if-range) + 1 + NP(expr)
if ([expr]) { [if-range] } else { [else-range] }NP(if-range)+ NP(else-range) + NP(expr)
while ([expr]) { [while-range] } NP(while-range) + NP(expr) + 1
do { [do-range] } while ([expr])NP(do-range) + NP(expr) + 1
for([expr1]; [expr2]; [expr3]) { [for-range] }NP(for-range) + NP(expr1)+ NP(expr2) + NP(expr3) + 1
switch ([expr]) { case : [case-range] default: [default-range] }S(i=1:i=n)NP(case-range[i]) + NP(default-range) + NP(expr)
[expr1] ? [expr2] : [expr3]NP(expr1) + NP(expr2) + NP(expr3) + 2
goto label1
break1
ExpressionsNumber of && and || operators in expression. Nooperators - 0
continue1
return1
Statement (even sequential statements)1
Empty block {}1
Function call1
Function(Method) declaration or BlockP(i=1:i=N)NP(Statement[i])

Rationale: Nejmeh says that his group had an informal NPATHlimit of 200 on individual routines; functions(methods) that exceededthis value were candidates for further decomposition - or atleast a closer look.Please do not be fanatic with limit 200- choose number that suites your project style. Limit 200 isempirical number base on some sources of at AT&T Bell Laboratoriesof 1988 year.

+

Checks the NPATH complexity against a specified limit.

The NPATH metric computes the number of possible executionpaths through a function(method). It takes into account the nesting ofconditional statements and multi-part boolean expressions(A && B, C || D, E ? F :G and their combinations).

The NPATH metric was designed base on Cyclomatic complexity toavoid problem of Cyclomatic complexity metric like nesting level within afunction(method).

Metric was described at "NPATH: a measure of execution pathcomplexity and its applications".If you need detailed description of algorithm, please read that article,it is well written and have number of examples and details.

Here is some quotes:

An NPATH threshold value of 200 has been establishedfor a function. The value 200 is based on studies doneat AT&T Bell Laboratories [1988 year].
Some of the most effective methods of reducing the NPATH value include:
Although strategies to reduce the NPATH complexityof functions are important, care must be taken not todistort the logical clarity of the software by applying astrategy to reduce the complexity of functions. That is,there is a point of diminishing return beyond which afurther attempt at reduction of complexity distorts thelogical clarity of the system structure.
Examples
Structure Complexity expression
if ([expr]) { [if-range] }NP(if-range) + 1 + NP(expr)
if ([expr]) { [if-range] } else { [else-range] }NP(if-range)+ NP(else-range) + NP(expr)
while ([expr]) { [while-range] } NP(while-range) + NP(expr) + 1
do { [do-range] } while ([expr])NP(do-range) + NP(expr) + 1
for([expr1]; [expr2]; [expr3]) { [for-range] }NP(for-range) + NP(expr1)+ NP(expr2) + NP(expr3) + 1
switch ([expr]) { case : [case-range] default: [default-range] }S(i=1:i=n)NP(case-range[i]) + NP(default-range) + NP(expr)
[expr1] ? [expr2] : [expr3]NP(expr1) + NP(expr2) + NP(expr3) + 2
goto label1
break1
ExpressionsNumber of && and || operators in expression. Nooperators - 0
continue1
return1
Statement (even sequential statements)1
Empty block {}1
Function call1
Function(Method) declaration or BlockP(i=1:i=N)NP(Statement[i])

Rationale: Nejmeh says that his group had an informal NPATHlimit of 200 on individual routines; functions(methods) that exceededthis value were candidates for further decomposition - or atleast a closer look.Please do not be fanatic with limit 200- choose number that suites your project style. Limit 200 isempirical number base on some sources of at AT&T Bell Laboratoriesof 1988 year.

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.metrics @@ -775,13 +775,13 @@ com.puppycrawl.tools.checkstyle.checks.modifier.InterfaceMemberImpliedModifierCh Package: com.puppycrawl.tools.checkstyle.checks.modifier com.puppycrawl.tools.checkstyle.checks.modifier.ModifierOrderCheck: Description: | -

Since Checkstyle 3.0

Checks that the order of modifiers conforms to the suggestions inthe JavaLanguage specification, sections 8.1.1, 8.3.1, 8.4.3 and 9.4. The correct order is:

  1. public
  2. protected
  3. private
  4. abstract
  5. default
  6. static
  7. final
  8. transient
  9. volatile
  10. synchronized
  11. native
  12. strictfp

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:

  1. public
  2. protected
  3. private
  4. abstract
  5. default
  6. static
  7. final
  8. transient
  9. volatile
  10. synchronized
  11. native
  12. 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 com.puppycrawl.tools.checkstyle.checks.modifier.RedundantModifierCheck: Description: | -

Since Checkstyle 3.0

Checks for redundant modifiers in:

  1. Interface and annotation definitions.
  2. Final modifier on methods of final and anonymous classes.
  3. Inner interface declarations that are declaredas static.
  4. Class constructors.
  5. Nested enum definitions that are declaredas static.

Rationale: The Java Language Specification stronglydiscourages the usage of public and abstract for methoddeclarations in interface definitions as a matter of style.

Interfaces by definition are abstract so the abstractmodifier on the interface is redundant.

Classes inside of interfaces by definition are public and static,so the public and static modifierson the inner classes are redundant. On the other hand, classesinside of interfaces can be abstract or non abstract.So, abstract modifier is allowed.

Fields in interfaces and annotations are automaticallypublic, static and final, so these modifiers are redundant aswell.

As annotations are a form of interface, their fields are alsoautomatically public, static and final just as theirannotation fields are automatically public and abstract.

Enums by definition are static implicit subclasses of java.lang.Enum<E>.So, the static modifier on the enums is redundant. In addition,if enum is inside of interface, public modifier is also redundant.

Enums can also contain abstract methods and methods which can be overridden by thedeclared enumeration fields.See the following example:


public enum EnumClass {
FIELD_1,
FIELD_2 {
@Override
public final void method1() {} // violation expected
};

public void method1() {}
public final void method2() {} // no violation expected
}

Since these methods can be overridden in these situations, the final methods are notmarked as redundant even though they can't be extended by other classes/enums.

Nested enum types are always static by default.

Final classes by definition cannot be extended so the finalmodifier on the method of a final class is redundant.

Public modifier for constructors in non-public non-protected classesis always obsolete:


public class PublicClass {
public PublicClass() {} // OK
}

class PackagePrivateClass {
public PackagePrivateClass() {} // violation expected
}

There is no violation in the following example,because removing public modifier from ProtectedInnerClassconstructor will make this code not compiling:


package a;
public class ClassExample {
protected class ProtectedInnerClass {
public ProtectedInnerClass () {}
}
}

package b;
import a.ClassExample;
public class ClassExtending extends ClassExample {
ProtectedInnerClass pc = new ProtectedInnerClass();
}

+

Checks for redundant modifiers.

Rationale: The Java Language Specification stronglydiscourages the usage of public and abstract for methoddeclarations in interface definitions as a matter of style.

The check validates:

  1. Interface and annotation definitions.
  2. Final modifier on methods of final and anonymous classes.
  3. Inner interface declarations that are declaredas static.
  4. Class constructors.
  5. Nested enum definitions that are declaredas static.

Interfaces by definition are abstract so the abstractmodifier on the interface is redundant.

Classes inside of interfaces by definition are public and static,so the public and static modifierson the inner classes are redundant. On the other hand, classesinside of interfaces can be abstract or non abstract.So, abstract modifier is allowed.

Fields in interfaces and annotations are automaticallypublic, static and final, so these modifiers are redundant aswell.

As annotations are a form of interface, their fields are alsoautomatically public, static and final just as theirannotation fields are automatically public and abstract.

Enums by definition are static implicit subclasses of java.lang.Enum<E>.So, the static modifier on the enums is redundant. In addition,if enum is inside of interface, public modifier is also redundant.

Enums can also contain abstract methods and methods which can be overridden by thedeclared enumeration fields.See the following example:


public enum EnumClass {
FIELD_1,
FIELD_2 {
@Override
public final void method1() {} // violation expected
};

public void method1() {}
public final void method2() {} // no violation expected
}

Since these methods can be overridden in these situations, the final methods are notmarked as redundant even though they can't be extended by other classes/enums.

Nested enum types are always static by default.

Final classes by definition cannot be extended so the finalmodifier on the method of a final class is redundant.

Public modifier for constructors in non-public non-protected classesis always obsolete:


public class PublicClass {
public PublicClass() {} // OK
}

class PackagePrivateClass {
public PackagePrivateClass() {} // violation expected
}

There is no violation in the following example,because removing public modifier from ProtectedInnerClassconstructor will make this code not compiling:


package a;
public class ClassExample {
protected class ProtectedInnerClass {
public ProtectedInnerClass () {}
}
}

package b;
import a.ClassExample;
public class ClassExtending extends ClassExample {
ProtectedInnerClass pc = new ProtectedInnerClass();
}

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 @@ -884,31 +884,31 @@ com.puppycrawl.tools.checkstyle.checks.naming.TypeNameCheck: Package: com.puppycrawl.tools.checkstyle.checks.naming com.puppycrawl.tools.checkstyle.checks.regexp.RegexpCheck: Description: | -

Since Checkstyle 4.0

A check that makes sure that a specified pattern exists, exists lessthan a set number of times, or does not exist in the file.

This check combines all the functionality provided byRegexpHeaderexcept supplying the regular expression from a file.

It differs from them in that it works in multiline mode.Its regular expression can span multiple lines and it checks thisagainst the whole file at once.The others work in singleline mode.Their single or multiple regular expressions can only span one line.They check each of these against each line in the file in turn.

Note: Because of the different mode of operation there may besome changes in the regular expressions used to achieve a particular end.

In multiline mode...

Note: Not all regular expression engines are created equal. Some provide extrafunctions that others do not and some elements of the syntax may vary.This check makes use of thejava.util.regex package; please check its documentation fordetails of how to construct a regular expression to achieve a particulargoal.

Note: When entering a regular expression as a parameter in theXML config file you must also take into account the XML rules. e.g. ifyou want to match a < symbol you need to enter &lt;. The regularexpression should be entered on one line.

+

A check that makes sure that a specified pattern exists, exists lessthan a set number of times, or does not exist in the file.

This check combines all the functionality provided byRegexpHeaderexcept supplying the regular expression from a file.

It differs from them in that it works in multiline mode.Its regular expression can span multiple lines and it checks thisagainst the whole file at once.The others work in singleline mode.Their single or multiple regular expressions can only span one line.They check each of these against each line in the file in turn.

Note: Because of the different mode of operation there may besome changes in the regular expressions used to achieve a particular end.

In multiline mode...

Note: Not all regular expression engines are created equal. Some provide extrafunctions that others do not and some elements of the syntax may vary.This check makes use of thejava.util.regex package; please check its documentation fordetails of how to construct a regular expression to achieve a particulargoal.

Note: When entering a regular expression as a parameter in theXML config file you must also take into account the XML rules. e.g. ifyou want to match a < symbol you need to enter &lt;. The regularexpression should be entered on one line.

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.regexp com.puppycrawl.tools.checkstyle.checks.regexp.RegexpMultilineCheck: Description: | -

Since Checkstyle 5.0

A check for detecting that matches across multiple lines.Works with any file type.

Rationale: This check can be used to when the regularexpression can be span multiple lines.

+

A check for detecting that matches across multiple lines.Works with any file type.

Rationale: This check can be used to when the regularexpression can be span multiple lines.

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.regexp com.puppycrawl.tools.checkstyle.checks.regexp.RegexpOnFilenameCheck: Description: | -

Since Checkstyle 6.15

Implementation of a check that looks for a file name and/or path match (or mis-match)against specified patterns. It can also be used to verify files match specific namingpatterns not covered by other checks (Ex: properties, xml, etc.).

When customizing the check, the properties are applied in a specific order.The fileExtensions property first picks only files that match any of thespecific extensions supplied.Once files are matched against the fileExtensions, the match property is thenused in conjunction with the patterns to determine if the check is lookingfor a match or mis-match on those files. If the fileNamePattern issupplied, the matching is only applied to the fileNamePattern and not thefolderPattern. If no fileNamePattern is supplied, then matching is appliedto the folderPattern only and will result in all files in a folder to bereported on violations. If no folderPattern is supplied, then all foldersthat checkstyle finds are examined for violations.The ignoreFileNameExtensions property drops the file extension and appliesthe fileNamePattern only to the rest of file name. For example, if the file isnamed 'test.java' and this property is turned on, the pattern is only appliedto 'test'.

If this check is configured with no properties, then the default behaviorof this check is to report file names with spaces in them.When at least one pattern property is supplied, the entire check is underthe user's control to allow them to fully customize the behavior.

It is recommended that if you create your own pattern, to alsospecify a custom violation message. This allows the violation message printedto be clear what the violation is, especially if multiple RegexpOnFilenamechecks are used.Argument 0 for the message populates the check's folderPattern.Argument 1 for the message populates the check's fileNamePattern.The file name is not passed as an argument since it is part of CheckStyle'sdefault violation messages.

+

Implementation of a check that looks for a file name and/or path match (or mis-match)against specified patterns. It can also be used to verify files match specific namingpatterns not covered by other checks (Ex: properties, xml, etc.).

When customizing the check, the properties are applied in a specific order.The fileExtensions property first picks only files that match any of thespecific extensions supplied.Once files are matched against the fileExtensions, the match property is thenused in conjunction with the patterns to determine if the check is lookingfor a match or mis-match on those files. If the fileNamePattern issupplied, the matching is only applied to the fileNamePattern and not thefolderPattern. If no fileNamePattern is supplied, then matching is appliedto the folderPattern only and will result in all files in a folder to bereported on violations. If no folderPattern is supplied, then all foldersthat checkstyle finds are examined for violations.The ignoreFileNameExtensions property drops the file extension and appliesthe fileNamePattern only to the rest of file name. For example, if the file isnamed 'test.java' and this property is turned on, the pattern is only appliedto 'test'.

If this check is configured with no properties, then the default behaviorof this check is to report file names with spaces in them.When at least one pattern property is supplied, the entire check is underthe user's control to allow them to fully customize the behavior.

It is recommended that if you create your own pattern, to alsospecify a custom violation message. This allows the violation message printedto be clear what the violation is, especially if multiple RegexpOnFilenamechecks are used.Argument 0 for the message populates the check's folderPattern.Argument 1 for the message populates the check's fileNamePattern.The file name is not passed as an argument since it is part of CheckStyle'sdefault violation messages.

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.regexp com.puppycrawl.tools.checkstyle.checks.regexp.RegexpSinglelineCheck: Description: | -

Since Checkstyle 5.0

A check for detecting single lines that match a suppliedregular expression. Works with any file type.

Rationale: This check can be used to prototype checks and tofind common bad practice such as calling ex.printStacktrace(), System.out.println(), System.exit(), etc.

+

A check for detecting single lines that match a suppliedregular expression. Works with any file type.

Rationale: This check can be used to prototype checks and tofind common bad practice such as calling ex.printStacktrace(), System.out.println(), System.exit(), etc.

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.regexp com.puppycrawl.tools.checkstyle.checks.regexp.RegexpSinglelineJavaCheck: Description: | -

Since Checkstyle 6.0

This class is variation on RegexpSingleline for detectingsingle lines that match a supplied regular expression in Java files. It supportssuppressing matches in Java comments.

+

A check for detecting single lines that match a suppliedregular expression in Java files.

This class is variation onRegexpSingleline for detectingsingle lines that match a supplied regular expression in Java files. It supportssuppressing matches in Java comments.

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.regexp From fe34b7d5306e50e07895e093dce41c36222b9d44 Mon Sep 17 00:00:00 2001 From: Filipe Esperandio Date: Mon, 11 Nov 2019 18:30:46 -0300 Subject: [PATCH 2/2] Speed up clone --- bin/scrape-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bin/scrape-docs b/bin/scrape-docs index 37ded98..b487ad1 100755 --- a/bin/scrape-docs +++ b/bin/scrape-docs @@ -15,7 +15,7 @@ issue_content = {} CHECKSTYLE_VERSION = File.read('CHECKSTYLE_VERSION').chomp if !Dir.exists? "data/" - system "git clone https://github.com/checkstyle/checkstyle.git data/" or raise "clone failed" + system "git clone --shallow-since=2019-01-01 https://github.com/checkstyle/checkstyle.git data/" or raise "clone failed" end system "cd data && git checkout master 1>/dev/null 2>/dev/null && git pull origin master 1>/dev/null 2>/dev/null" or raise "pull failed"