从 CheckStyle 生成编码指南答案

【问题标题】：Generate Coding guidelines from CheckStyle从 CheckStyle 生成编码指南
【发布时间】：2013-01-05 22:40:42
【问题描述】：

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

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

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

【问题讨论】：

同时开始遵循始终可用的 DIY 方法，创建了一个带有示例 xsl 转换设置的 gitHub 存储库。 link
这是错误的。想象一下，当您的开发人员发现他们的编码指南是从 Checkstyle 配置中生成时，他们会有什么感受！当指南本应是一份精心制作的文档时，不仅仅谈论风格。
我同意你的观点，目的不是生成最终的代码风格手册，只是解释规则集的扩展。如果你有一些 checksyle 配置，你可能有一些自定义设置。您将如何向新团队成员展示这些自定义设置？
您将如何向新团队成员展示这些自定义设置？ 对于 Checkstyle，我建议将消息文本设置为清楚地解释问题所在（即解释命名约定而不是给出不匹配的正则表达式）。没有人愿意打开外部文档来正确修复 Checkstyle 警告（尽管命名约定的详细版本应该在其中）。
这是个好主意。我会接受这个作为答案，如果你用一些样本来扩展它，让它更详细一点。一年后，我觉得对这样的工具的需求并不大。 :)（在正常的开发人员日期间，从未打算强迫任何人使用它，但在派生类中可能会很好）

标签： java html coding-style report checkstyle

【解决方案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}$'

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

【讨论】：

【解决方案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

【讨论】：