Stylecop 设置在什么时候不再有用并开始变得烦人？

Question

我在一个团队工作，我们在 StyleCop 中使用广泛的规则集，我想知道对于这样的工具不再有用并且开始变得烦人的一般观点有什么想法。我们还使用 GhostDoc，因此代码中充满了 XML 注释，这使得代码更难以阅读和审查。我对 XML 注释没有任何问题，并且发现它们在某些地方非常有用，但是每个字段和属性真的需要它们吗？

我们有一个令人钦佩的目标“每个项目在构建时必须有 0 个警告”，但这个目标肯定需要违反合理的 StyleCop 规则集，否则宝贵的时间会浪费在“修复”StyleCop 警告的原因上。

对此有何想法？

编辑 我现在实际上想知道像 stylecop 这样的工具到底有什么论据？为什么不放弃它，让合理的编码标准和良好的代码审查来处理剩下的事情呢？尤其是在一个优秀的有能力的团队中？当然，获得 0 个警告的任务实际上会增加价值，因为所有警告都是相关的。

我认为 GhostDoc 的唯一优点是它可以为您从头开始编写 XML 注释节省宝贵的几秒钟时间。我认为您不应该在不编辑的情况下接受生成的评论 - 这可能会适得其反。

这是由 GhostDoc 生成的 xml 注释满足的 Stylecop 规则（SA1642：ConstructorSummaryDocumentationMustBeginWithStandardText）的组合 - 是否在一天结束时添加任何值？

    /// <summary>
    /// Initializes a new instance of the <see cref="SomeCustomType"/> class.
    /// </summary>
    /// <param name="someParameter">The someParameter.</param>
    public SomeCustomType(string someParameter)
    {
    }

Answer 1

我认为这更像是一种咆哮而不是一个问题，但我同意你的观点：

• 过度执行的风格规则是一件坏事。

虽然显然应该有源代码格式的指导方针，但过度规定的牢不可破的规则会导致令人不快的极端情况。在所有情况下严格遵守规则可能会生成难以阅读的混乱或过度包装的代码。

编码是一种不同的写作方式，因此奥威尔的奖励规则——“打破任何这些规则，不要说任何彻头彻尾的野蛮行为”——也需要适用于编码风格指南。

我怀疑在一个由能够设置和理解样式指南的有能力的程序员组成的团队中，自动执行样式是否是一个好主意。自动 lint 对于发现意外错误很有用，但如果应用于代码格式化的高度规范性法律，它们就无法考虑奥威尔规则。有了强大的规则集，这可能会迫使您在可维护性的幌子下编写难以维护的代码。

如果你的团队中有能力较差的编码员，他们的输出是混乱的，除非强制风格化，那么强制执行可能是一个好主意。 （但是你可能会遇到更大的问题！）

• 自动评论是一件非常糟糕的事情，

我以前没有见过 GhostDoc，但实际上我有点震惊。

他们自己首页上的这个例子

/// <summary>
///     Determines the size of the page buffer.
/// </summary>
/// <param name="initialPageBufferSize">
///     Initial size of the page buffer.
/// </param>
/// <returns></returns>
public int determineBufferSize(int initialPageBufferSize) {

几乎是坏评论的典型例子，对它所记录的代码添加了绝对零的洞察力。这绝对比没有评论文档更糟糕。

Javadoc 遵循的所有源文档内模式有时都有点可疑，因为它们将源代码与通常针对最终用户（与阅读代码的受众完全不同的受众）的材料混在一起。但这绝对是坑。我无法想象谁认为这是个好主意。

Answer 2

StyleCop 是一个工具。它不应该是完美的开箱即用，也不应该满足每个人的需求。

我个人说“是的，这很重要”——因为当您管理一个开发团队时，StyleCop 可以帮助您确保遵守您的编码指南。这正是其目的：以自动化、可测量、一致的方式评估编码标准。如果您不想在构建过程中执行此操作，那么您是对的 - 这是浪费时间。

您自己说过：零警告目标“需要违反合理的 StyleCop 规则集”。运行任何配置不符合您需求的工具都是没有意义的。如果一条规则对你来说“烦人”，那么就将其关闭——但对其他人来说，它可能至关重要。

至于你的“是否增加价值”的问题：是的。人们低估了一致性的价值。如果所有构造函数都具有相同的注释风格，如果项目中属性的所有智能感知都具有相同的结构，那么需要处理的心理障碍（无论多小）就少了一个。借助自动化工具，几乎可以实现零工作量。有什么可抱怨的？

Answer 3

当围绕规则进行编码所花费的时间比通过减少维护所获得的时间要多时。

如您所知，修复错误比编写错误要花费更多的时间，因此在达到阈值之前，您仍然可以做大量额外的工作来使代码更加健壮和可维护。

Answer 4

代码写得好、可读/可维护是至关重要的，但我们使用 Visual Studio 和 Resharper 的自动代码格式化助手来处理我们的代码，并使用 AtomineerUtils 将 XML 文档注释保持在严格定义和整洁的格式中。

因此，主要的 StyleCop 规则是无关紧要的，因为我们的代码始终“默认”遵守重要规则。较小的 StyleCop 规则对于日常使用来说往往过于严格。 （大多数这些规则只能对代码的质量或可读性做出微小的（如果有的话）改进，因此我们发现遵守它们的成本是不可接受的。我们允许程序员有一点“表达自由”——只要他们的代码团队中的其他人很容易阅读，我们不介意编码风格的微小变化）。因此，在评估 StyleCop 后，我无法找到任何现实世界的好处。

相比之下，我们发现 FXCop 非常有用，因为它突出显示的问题不仅仅是小的可读性问题 - 它会不时发现严重的错误和性能问题。

Answer 5

你的问题有几点引起了我的注意，所以我想在之前的回答的基础上补充一些想法。

我对 XML 注释没有任何问题，并且发现它们在某些地方非常有用，但它们真的在每个字段和属性上都需要吗？

有些字段和属性对每个人来说都是显而易见的，不需要解释。例如，如果类 Cooperative 具有属性 X、Y 和 Z，则无需解释的评论。

但对于像 StyleCop 这样的工具，在第一次发现源代码时，工具无法区分明显的属性和可能难以理解的属性。所以不，并不是所有地方都需要注释，但我们要么对每个字段和属性强制注释，要么禁用该规则并让开发人员决定。

这是由 GhostDoc 生成的 xml 注释满足的 Stylecop 规则（SA1642：ConstructorSummaryDocumentationMustBeginWithStandardText）的组合 - 是否在一天结束时添加任何值？

不知何故。有些工具像其他方法一样显示构造函数，并且您无法在视觉上区分两者（除非您记住类的名称）。另一方面，XML 注释非常清晰，因此很容易理解这是一个构造函数。

顺便问一下，你还想在这里写什么？

• 还有别的事吗？没有构造函数的标准将导致阅读代码和理解方法是视图中的构造函数（两者以相同的方式显示）变得困难。

• 完全没有评论吗？它可以是一个解决方案，因为这样的注释可以很容易地从类的名称生成。但这会让事情变得更加复杂（为什么要自动生成对构造函数而不是其他方法的注释？）。另外，如果您没有提供此构造函数的描述，那么有人怎么知道someParameter是什么？

---

最后，回答你的问题，没有人可以说每条 StyleCop 规则在每种情况下都总是有用。但请记住，这里的废话是“每个项目构建时必须有 0 个警告”的目标，而不是 StyleCop 本身。如果您是一位经验丰富的开发人员并且编写了干净的代码，那么没有理由不关闭某些 StyleCop 规则，至少如果您很好地理解它们的含义、它们为什么在这里以及不遵守规则会产生什么后果。

在我们公司，我们有一项政策，要求每个项目都使用 StyleCop，如果一个小项目有数百个警告，那么就有问题了。同时，我经常遇到这样的情况：我在整个类上禁用了一些 StyleCop 规则，只是因为执行它们会浪费时间，而且不会给任何人带来任何东西。另一方面，当我的同事禁用 FxCop/StyleCop 只是以便能够用法语编写类、方法和属性的名称时，我一点也不感激（我在一家法国公司，也适用于说英语的开发人员），所以我想说，对于某些人来说，这两种工具都必须每次都启用，而无法禁用它们。

Answer 6

拥有一个每个人都使用的固定样式是很有用的，并且对于新代码StyleCop 将强制执行这一点以使每个人受益。

但是，当将 StyleCop 添加到用不同风格编写的现有项目时，您将遇到数百、数千或数万次违反内容的情况。本质上是任意规则，例如：

• if 后面必须跟一个空格
• 函数参数必须全部出现在同一行或每个单独的行
• 单行注释必须以空格
• 开头 字段之间必须有一个空行 左
• 大括号后面不能有空行 字段
• 名称不能以下划线开头或带前缀 不应
• 使用默认参数，应使用重载
• 请勿在本地调用前添加 this
• 使用语句的顺序

仅仅为了遵守这样的规则而编辑数千个现有文件和数十万行代码是没有意义的。

• 任何更改都有可能引入错误。
• 如果您进行更改不是为了修复错误或引入功能，那么您为什么要这样做？

如果答案是“让 StyleCop 闭嘴”——老实说——有不止一种方法可以做到这一点。

您的目标应该是消除不代表错误的警告，以便您可以看到 - 然后修复 - 更有问题的警告，这可能会起作用。存在 1500 个有关单行注释格式的警告是您可以摆脱的障碍。

因此，在遗留代码库中：

• 编辑规则集以禁用任何任意的、具有多种违规行为的风格规则。这些麻烦大于其价值：没有什么坏事会发生。发生这种情况是因为该项目在字段中使用下划线，但如果您尝试修复它时不小心导致命名冲突，则可能会发生这种情况。
• 如果存在一两个违规行为，请仔细考虑使用抑制文件是否比编辑工作的、经过测试的代码更好，只是为了关闭风格警告。您不需要放入变更集数百个文件中存在数千个空格更改。当您认为只是重新格式化一个块时，很容易引入行为差异，并且在检查更改的行时很容易错过这样的事情。
• 只有当您确信违反规则代表一个错误时，您才应该更改代码。那么如果参数不在同一行怎么办？如果您需要立即理解它，并且格式使这变得困难，请务必重新格式化代码。但不仅仅因为StyleCop这么说。
• 即使添加参数文档也不一定是无害的：如果您不了解代码的全部内容，您可能只是在为下一个开发人员灌输自己的误解。