Question

有没有办法从现有的CheckStyle配置文件中生成'nice'编码约定/指南文档？

此文档必须包含所执行规则的说明以及配置值（如最大行长度，违规严重程度等）。

拥有此类文档的好处是可以更快地提升新团队成员，而无需阅读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

从CheckStyle生成编码指南

2 个答案: