在什么时候，Stylecop的设置停止有用并开始变得烦人？

Question

我在一个团队中工作，我们使用广泛的StyleCop规则集，我想知道这样的工具何时停止有用并开始变得恼人。我们还使用GhostDoc，所以代码中充满了XML注释，这使得代码变得更难读，难以审核。我对XML注释没有问题，在某些地方我发现它们非常有用，但是它们真的需要在每个字段和属性上吗？

我们有一个令人钦佩的目标，即“每个项目在构建时必须具有0个警告”，但是这个目标肯定需要根据合理的StyleCop规则集进行评估，否则就会浪费宝贵的时间来“修复”StyleCop警告的原因。

对此有什么想法吗？

编辑 我现在实际上在思考stylecop这样的工具的存在意义是什么？为什么不放弃它，让明智的编程标准和良好的代码审查处理剩下的部分？尤其是在一个良好的胜任团队中？那么获得0个警告的任务实际上会增加价值，因为所有警告都将是相关的。

我认为GhostDoc唯一的优点就是可以节省您从头开始编写XML注释的重要几秒钟时间。我认为您不应该接受生成的注释而不进行编辑 - 这可能是适得其反的。

这里是Stylecop规则（SA1642：ConstructorSummaryDocumentationMustBeginWithStandardText）与GhostDoc生成的XML注释的组合 - 最终是否有任何价值？

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

- Peter Kelly

Answer 1

这更像是一个牢骚而不是问题，我同意你的观点：过于强制执行的代码风格规则是不好的。虽然显然应该有源代码格式化的准则，但是过于规定死规则会导致讨厌的边角情况。在所有情况下严格遵守规则可能会生成难以阅读的混乱代码或过度换行的代码。编码是一种写作形式，因此奥威尔的加分规则——“与其说任何野蛮的话，不如打破这些规则中的任何一条。”——也需要适用于编码样式指南中。

我怀疑自动化样式执行在一支由能够设置和理解样式指南的程序员组成的团队中是否是个好主意。自动化纠错对于捕捉意外错误是有用的，但如果使用高度具体的代码格式规则来应用，则无法考虑到奥威尔的规则。使用强大的规则集可能会迫使您在可维护性的幌子下编写更难以维护的代码。如果您的团队中有不那么熟练的编码人员，并且他们的输出除非被强制遵循样式否则会变得杂乱无章，那么执行样式可能是个好主意。（但这样你可能会有更大的问题！）

自动化注释非常糟糕，我之前从未见过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的源内文档模式有时都有点可疑，因为它们会将面向终端用户的材料与阅读代码的人群混在一起。但这个实在太糟糕了。我无法想象谁认为这是个好主意。

- bobince

---

这可能更像是一场发泄，而不是一个问题！但我很高兴你的回答也变成了对自动评论生成器的抱怨！我正在审查我们的风格和代码标准，我们的团队非常有能力，所以我想建议如果我们都同意StyleCop实际上没有增加任何真正价值，那么它实际上可以被放弃。你提到的关于这些样式规则给人们安全感的错觉的观点+1 - 一种虚假的安全感。 - Peter Kelly

这确实很可怕，实际上可能是注释不应该存在的一个例子。任何糟糕的布局或命名约定都应该被代码审查捕捉到。我开始想知道像StyleCop这样的工具的论点是什么... - Peter Kelly

良好运行并具有合理的设置，它可能是一种有用的方式，用于捕捉眼睛可能不会立即注意到的花括号/缩进不匹配等 sneaky 错误。 - bobince

非常感谢你对GhostDoc的抨击 - 我本来也想添加它，但幸好这里还有其他清醒的人。有人几年前决定在我们的整个代码库中使用它，结果引起了巨大的问题。其中最小的问题是，我们的注释覆盖工具现在显示我们有100%的覆盖率，但所有的注释都是无用的。我们唯一的选择就是费力地检查每个注释并替换GhostDoc生成的注释。最终，我们告诉那个程序员撤销他的更改，然后在不更改注释的情况下添加代码更改。 - HiredMind

Answer 2

StyleCop是一个工具。它不应该一开始就完美，也不能满足所有人的需求。

个人认为“是的，它很重要” - 因为当你运行开发团队时，StyleCop可以帮助您确保遵守编码准则。这正是它的目的：以自动化、可衡量、一致的方式评估编码标准。如果您不想在构建过程中进行此操作，则正确 - 这是浪费时间。

您自己说零警告目标“需要对合理的StyleCop规则集进行”。使用不符合您需求的配置运行任何工具都没有意义。如果某个规则对您来说很“烦人”，那么将其关闭 - 但对其他人来说，它可能非常重要。

至于您的“是否增加价值”的问题：是的。人们低估了一致性的价值。如果您项目中的所有构造函数都具有相同的注释风格，如果所有属性的Intellisense结构都相同，那么它就少了一个（无论多小）心理障碍需要处理。而且使用自动化工具，几乎不需要付出任何努力。有什么好抱怨的呢？

- Dan Puzey

---

无用的注释一致性并不是一个价值。代码应该是一种“活”的东西，它会变化和发展成为更好的东西。规则和代码风格也是如此。在我的经验中，当一个公司采用StyleCop多年后，要改变那种“心态”和“坏”习惯（比如写“机器人式”的注释）是非常困难的。然而，在我的经验中，这是改进的一个障碍。我想大多数使用StyleCop的公司只是使用默认规则。 - Alex 75

Answer 3

当花费更多的时间编写规则以避免代码维护成本时，你可以考虑是否值得这样做。

众所周知，修复一个错误需要比编写它花费更多的时间，因此在达到临界点之前，你仍然可以进行大量额外的工作，使代码更加健壮和可维护。

- Guffa

---

同意。我觉得我可能会对所有的代码风格标准都产生厌恶。一旦有了良好的编码标准以及有意义的、描述性的注释，那么代码风格规则就是无关紧要的。 - Peter Kelly

Answer 4

代码的书写和可读性/可维护性非常重要，但我们使用Visual Studio和Resharper的自动代码格式化工具以及AtomineerUtils来保持XML文档注释的严格定义和整洁格式。

因此，主要的StyleCop规则是无关紧要的，因为我们的代码始终默认遵循重要的规则。次要的StyleCop规则往往过于严格，不适合日常使用。（这些规则大多只对代码的质量或可读性产生微小甚至没有改进，因此我们认为遵守它们的成本是不可接受的。我们允许程序员有一定的“自由表达”，只要他们的代码易于被团队中的其他人阅读，我们不介意编码风格的小变化）。因此，在评估了StyleCop之后，我无法找到任何真正的现实优势。

相比之下，我们发现FXCop非常有用，因为它所强调的问题不仅仅是关于代码可读性的小问题，而且还会时不时地发现严重的错误和性能问题。

- Jason Williams

Answer 5

你的问题引起了我的注意，我想在之前的回答中加入一些想法。

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

有些字段和属性对于每个人来说都是显而易见的，它们不需要解释。例如，如果一个类Coordinate具有属性X、Y和Z，那么在注释中就没有什么需要解释的了。

但是当涉及到像StyleCop这样的工具时，工具无法区分显而易见的属性和可能难以理解的属性，特别是在第一次发现源代码时。因此，不是每个地方都需要注释，但我们要么强制在每个字段和属性上添加注释，要么禁用规则并让开发人员决定。

这是一个Stylecop规则（SA1642：ConstructorSummaryDocumentationMustBeginWithStandardText）与GhostDoc生成的XML注释相结合的例子 - 最终是否会增加任何价值呢？

有些工具会像其他方法一样显示构造函数，视觉上无法区分两者（除非您记得类的名称）。而另一方面，XML注释非常清晰，使人们很容易理解这是一个构造函数。

顺便问一下，在这里还有什么需要写的吗？

• 还有其他内容吗？不为构造函数制定标准将使代码难以阅读，并且在同时显示两者的情况下，很难理解方法是构造函数。

• 没有任何评论吗？这也可以是一种解决方案，因为此类评论可以轻松从类的名称中生成。但这将使事情变得更加复杂（为什么只对构造函数自动生成注释而不是其他方法？）。此外，如果您未对此构造函数提供说明，如何让他人知道someParameter是什么？

---

最后，回答你的问题，没有人能说每个StyleCop规则在每种情况下都是有用的。但请记住，“每个项目构建时必须有0个警告”的目标才是无意义的，而不是StyleCop本身。如果你是一位经验丰富的开发者并且编写干净的代码，那么就没有理由不关闭一些StyleCop规则，至少要了解它们的含义、为什么存在以及不遵循规则会产生什么后果。

在我们公司，我们有一个政策，对于每个项目都使用StyleCop，如果一个小项目有数百个警告，那么就存在问题。同时，我经常遇到这样的情况，即在整个类上禁用了一些StyleCop规则，只是因为强制执行它们会浪费时间，而且对任何人都没有好处。另一方面，当我的同事禁用FxCop/StyleCop只是为了能够用法语编写类、方法和属性名称时，我完全不赞成（我在一家与英语开发人员合作的法国公司工作），因此我认为对于某些人来说，这两个工具必须始终启用，不能禁用。

- Arseni Mourzenko

Answer 6

拥有一套大家都使用的样式是很有用的，对于新代码，StyleCop将强制执行这一点，使每个人受益。

但是，当将StyleCop添加到使用不同样式编写的现有项目中时，您将会遇到数百、数千或数万个违反基本上是任意规则的违规情况，例如：

• if后必须跟一个空格
• 函数参数必须全部出现在同一行或各自单独一行
• 单行注释必须以空格开头
• 字段之间必须有空行
• 开括号后不能有空行
• 字段名不能以下划线开头或带前缀
• 不应使用默认参数，而应使用重载
• 不要在局部调用前加前缀 this
• Using语句的顺序

修改成千上万行的现有代码以符合这些规则根本没有意义。

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

如果答案是“为了让StyleCop闭嘴” - 而且要诚实 - 那么有多种方法可以做到这一点。

你的目标应该是消除不代表错误的警告，这样你就可以看到并解决更棘手的警告，它们可能会引起错误。存在1500个关于单行注释格式的警告是一个你可以避免的障碍。

因此，在传统代码库中：

• 编辑规则集以禁用任何有过多违规的任意风格规则。这些规则并不值得麻烦：由于项目使用下划线作为字段，因此不会发生任何不良情况，但如果您在试图修复此问题时意外引起命名冲突，可能会出现问题。
• 当只有一两个违例时，请仔细考虑是否更好使用抑制文件而不是编辑已经工作、经过测试的代码来关闭一个风格警告。你不需要在数百个文件中放入成千上万的空格变化的修改集。当你认为你只是重新格式化一个块时，很容易引入行为差异，很容易漏掉这种变化，因此要慎重。
• 只有在确定规则违反代表错误时才应更改代码。如果参数不在同一行，那又怎样呢？如果您需要理解它并且格式使其难以理解，则可以随意重新格式化代码。但是不要仅仅因为 StyleCop 这样说。
• 即使添加参数文档也不一定是无害的：如果您不完全了解代码，您可能只是为下一个开发人员固化自己的误解。

- Ben