Generate Coding guidelines from CheckStyle

Question

Is there a way to generate a 'nice' Coding conventions / guidelines document from existing CheckStyle configuration file?

This document must contain the description of the rules enforced, and the configuration values (like the max line length, violation severity, etc).

The benefit of having such a document is to ramp up a new team member faster, without reading CheckStyle configuration file.

Answer 1

A few typical coding standards are given 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's class, from 1 to 8
    int age;   // The child's 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

Answer 2

I would generally advise against generating even parts of a coding guidelines document, because that would cause acceptance problems with your software engineers. Also, the Checkstyle rules should, in my humble opinion, not be part of the coding guidelines document itself. Instead, the coding guidelines should state something like "Take care not to cause Checkstyle issues."

The Checkstyle tool can be configured with information to show to the developer with the warning. That way, developers won't need to open an external document in order to resolve Checkstyle warnings correctly, because all required information is already there.

Example: The LocalVariableName check checks the naming convention for non-final local variables. Its default message text is:

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

If you configure the check like this:

<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 would be:

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

Admittedly, if all your developers knew their regular expressions well enough, the new message text will not be necessary. But not everybody is a regex expert, and this is just an example which can be applied to many checks, including checks without regexes.