我们如何强制为 jenkins 上的团队项目编写 java 注释？答案

【问题标题】：How do we enforce writing java comments for team projects on jenkins?我们如何强制为 jenkins 上的团队项目编写 java 注释？
【发布时间】：2018-05-08 09:38:21
【问题描述】：

我们需要在我们的团队项目 java 代码中强制使用 cmets。由于我们已经在使用 Jenkins，因此我们最好使用一个插件，该插件可以根据是否编写 cmets 来导致构建成功/失败。选项包括使用 Checkstyle、git hooks 或 SONAR 插件来执行相同的操作。感谢任何设置此设置的指针或提示。

请注意，我们打算将 Javadocs 用于注释目的。

【问题讨论】：

如果他们不这样做，就解雇他们。
哈哈！ @Stultuske
真的，这是唯一可行的方法。任何人都可以编写通过验证但仍然完全无用的评论，除非开发人员了解有用 cmets 的需求，否则您最终会得到。
插件的指标应该是什么？ cmets 行，所有参数都已注释，...？在大多数情况下，通过自动化工具强制 cmets 将是完全没用的，而且会令人沮丧（setter/getter 的无用注释；良好的代码风格 > 大量 cmets；大量注释文本并不能巩固质量）。在您的代码中引入有意义的 cmets 的唯一明智的方法是同行代码审查并让您的开发人员了解 cmets 为何有用。
我也认为这不是指标和构建环境的问题。这是“做你该死的工作”之类的东西。我从未听说过任何通过度量和构建工具强制执行有用的 cmets 的成功尝试。我听说过很多失败的。

标签： java sonarqube jenkins-plugins javadoc checkstyle

【解决方案1】：

使用Checkstyle plugin for Jenkins 是一个可行的选择。

如果将 Checkstyle 配置为仅检查与 cmets 相关的问题，它甚至可以满足您“根据是否编写 cmets 导致构建成功/失败”的要求，但您可能不会不想这样做，因为 Checkstyle 还可以通过许多其他方式帮助提高代码质量和一致性。

构建选项包括：

如果 Checkstyle 错误的数量超过某个绝对限制，则将 Jenkins 项目构建配置为失败。（例如，如果 Checkstyle 错误的数量 > 300，则此构建失败。）
如果 Checkstyle 错误的数量超过先前构建的错误数量某个定义的阈值，则将 Jenkins 项目构建配置为失败。（例如，如果 Checkstyle 错误的数量比以前的构建多 50 个以上，则此构建失败。）

但是，我相信这两种方法都是系统范围的，适用于所有构建。我认为您不能针对每个项目设置这些阈值。

使用Checkstyle for policing Javadoc comments的其他注意事项：

可以自定义任何 Checkstyle 错误消息以满足您的需求。
您可以使用 allowMissingPropertyJavadoc 允许 getter/setter 上缺少 cmets。
您可以使用 ignoreMethodNamesRegex 指定将忽略符合某些正则表达式的方法名称。
您可以使用 minLineCount 指定允许低于特定行数阈值的方法省略 Javadoc 注释。
您可以使用 allowMissingThrowsTags、allowMissingReturnTag 和 将 Checkstyle 配置为接受与方法的签名、返回类型和引发的异常不完全匹配的 Javadoc 注释>allowMissingParamTags（虽然我不清楚为什么有人想要这样做）。

很容易识别 Checkstyle 不够完美的特定区域，当然它不会（不能）审查您的 cmets 的质量，但这些并不是不使用它的理由。不要让完美成为美好的敌人； Checkstyle 将验证是否满足 Javadoc cmets 的最低要求。

【讨论】：