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

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.