Creating Encoding Rules with CheckStyle

Question

Is there a way to create a “good” code / document to document the rules from an existing CheckStyle configuration file?

This document should contain a description of the rules and configuration values ​​(for example, maximum line length, severity of violation, etc.).

The advantage of this document is to speed up the work of a new team member without reading the CheckStyle configuration file.

Answer 1

As a general rule, I would advise against creating even parts of the coding manual, as this can cause problems when receiving your software engineers. In addition, Checkstyle rules should, in my humble opinion, not be part of the coding document itself. Instead, the coding guidelines should say something like, "Be careful not to cause problems with Checkstyle."

The Checkstyle tool can be customized with information to show the developer a warning. Thus, developers will not need to open an external document to correctly resolve Checkstyle warnings, because all the necessary information already exists.

Example: LocalVariableName checks the naming convention for non-finite local variables. Default message text:

Member Names: Name 'Foo' must match pattern '^[az][a-zA-Z0-9]{0,31}$'. 

If you configure the check as follows:

 <module name="LocalVariableName"> <message key="name.invalidPattern" value="Local variable name ''{0}'' must not be longer than 32 alphanumeric characters and start with a lowercase letter. Regex: ''{1}''"/> </module> 

Then the output will be:

 Local variable name 'Foo' must not be longer than 32 alphanumeric characters and start with a lowercase letter. Regex: '^[az][a-zA-Z0-9]{0,31}$' 

Admittedly, if all your developers knew their regular expressions well, a new message text would not be needed. But not everyone is a regular expression expert, and this is just an example that can be applied to many validations, including validations without regular expressions.

Answer 2

A few typical coding standards are listed here:

 Comments: Write Javadoc comments for all classes, methods, and variables. Naming conventions: Class names should be nouns, in mixed case with the first letter of each internal word capitalized (MyClass). Variable names should be nouns, in mixed case with a lowercase first letter, and with the first letter of each internal word in upper case (myVariable). Constants should be in all uppercase with words separated by underscore (MY_CONSTANT_VALUE). Indentation: Spaces should be preferred to tabs for indenting purposes. Declarations: One declaration per line, with comments, for example: int class; // The child class, from 1 to 8 int age; // The child age rather than: int class, age; Statements: Opening braces in compound statements should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement, for example: while (i < 10) { i++; } Best practices: Use the final keyword for variables and parameters that will not need to be modified. Don't declare variables within loops