java - 从 CheckStyle 生成编码指南

Question

有没有办法从现有的 CheckStyle 配置文件中生成一个“不错的”编码约定/指南文档？

该文档必须包含强制执行规则的描述和配置值（如最大行长度、违规严重性等）。

拥有这样一个文档的好处是可以更快地培养新的团队成员，而无需阅读 CheckStyle 配置文件。

Answer 1

我通常建议不要生成编码指南文档的一部分，因为这会导致您的软件工程师出现验收问题。此外，在我看来，Checkstyle 规则不应成为编码指南文档本身的一部分。相反，编码指南应该声明“注意不要引起 Checkstyle 问题”。

Checkstyle 工具可以配置信息以向开发人员显示警告。这样，开发人员不需要打开外部文档来正确解决 Checkstyle 警告，因为所有必需的信息都已经存在。

示例：LocalVariableName检查检查非最终局部变量的命名约定。它的默认消息文本是：

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

如果您像这样配置检查：

<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>

那么输出将是：

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}$'

诚然，如果您的所有开发人员都足够了解他们的正则表达式，那么新的消息文本将不是必需的。但并不是每个人都是正则表达式专家，这只是一个可以应用于许多检查的示例，包括没有正则表达式的检查。

Answer 2

这里给出了一些典型的编码标准：

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