22

我在一个团队中工作，我们在 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)
    {
    }
4

6 回答 6

25

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

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

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

编码是一种写作形式，因此奥威尔的奖励规则——“打破任何这些规则，不要说任何完全野蛮的东西”——也需要适用于编码风格指南。

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

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

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

我以前没有看过 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 之后的所有 in-source-doc 模式有时有点令人怀疑，因为它们将源代码与通常针对最终用户的材料混在一起 - 与阅读代码的人完全不同的受众。但这绝对是坑。我无法想象谁认为这是个好主意。

于 2010-07-08T12:24:27.127 回答
13

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

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

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

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

于 2010-07-09T07:51:05.250 回答
4

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

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

于 2010-07-08T12:32:04.220 回答
3

代码编写良好且可读/可维护非常重要，但我们使用 Visual Studio 和 Resharper 的自动代码格式化助手来处理我们的代码，并使用 AtomineerUtils 以严格定义和整洁的格式保持 XML 文档注释。

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

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

于 2010-07-09T07:40:24.517 回答
1

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

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

有些字段和属性对每个人来说都很明显，不需要解释。例如，如果一个类Coordinate具有属性X,Y和Z，则注释中没有什么要解释的。

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

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

不知何故。一些工具像其他方法一样显示构造函数，并且您无法在两者之间产生任何视觉差异（除非您牢记类的名称）。另一方面，XML 注释非常清晰，很容易理解这是一个构造函数。

顺便说一句，你还会在这里写什么？

  • 还有什么？没有构造函数的标准将难以阅读代码并难以理解方法是视图中的构造函数，其中两者以相同的方式显示。

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

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

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

于 2011-04-09T20:44:20.687 回答
1

拥有一个每个人都使用的固定样式很有用，对于新代码StyleCop 将强制执行此操作以使每个人都受益。

但是，当将 StyleCop 添加到使用不同 style 编写的现有项目中时，您将获得数百、数千或数万次违反本质上任意规则的行为，例如：

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

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

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

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

您的目标应该是消除不代表错误的警告，以便您可以看到 - 然后修复 - 可能会出现更多问题的警告。存在 1500 条关于单行注释格式的警告是您可以克服的障碍。

因此，在遗留代码库中：

  • 编辑规则集以禁用任何具有多个违规行为的任意风格规则。这些麻烦多于其价值：不会发生任何不好的事情，因为该项目使用下划线作为字段，但如果您不小心导致命名冲突试图修复它，它可能会发生。
  • 如果存在一两个违规行为，请仔细考虑使用抑制文件是否比编辑工作的、经过测试的代码只是为了关闭风格警告更好。您不需要在数百个文件中放入包含数千个空白更改的变更集。当您认为您只是重新格式化一个块时，很容易引入行为差异，并且很容易错过回顾更改的行的这种事情。
  • 只有当您对违反规则表示错误感到满意时，您才应该更改代码。那么如果参数不在同一行怎么办？如果你现在需要理解它，那么无论如何都要重新格式化代码，而这种格式很难。但不仅仅是因为 StyleCop 这么说。
  • 即使添加参数文档也不一定是无害的：如果您对代码一无所知，您可能只是在为下一个开发人员制造您自己的误解。
于 2017-02-25T13:20:37.423 回答