21

我只是针对我的一些代码运行 style cop 并得到了一些：

SA1600: The field must have a documentation header.

现在不要误会我的意思，我喜欢风格警察，当你与一个以上的人一起工作时，这很棒，但这条规则对我来说似乎有点过分。为什么要添加：

    /// <summary>
    /// blah blah blah
    /// </summary>

到每个变量的顶部。我很确定我记得有人说（Martin Fowler，Kent Beck .. 不记得 ATM）评论应该说“为什么”而不是“什么”，我真的不明白你怎么能解释为什么多变的。

我还发现对每个变量都有注释的代码更难阅读，因为你看到的只是绒毛。

我的想法是，如果您必须解释每个变量是什么，那么您在命名方面确实失败了。

有没有其他人发现注释变量有点代码味道，或者只是我。

4

7 回答 7

19

这是一篇相当老的帖子，但在我自己寻找这个问题的解决方案时遇到了它，所以尽管我会提供一个解决方案。

如果您在规则编辑器中打开Settings.StyleCop文件，请选择文档规则节点，然后在右侧的详细设置部分中取消选择包含字段选项。现在您将不再需要记录字段。

于 2011-07-20T07:52:13.123 回答
12

我不会说评论变量总是一种代码味道（听起来也不是你要说的）。我确实同意评论每一个变量，每一次至少是过度的，并且可能表明命名不佳。事实上，有些人会争辩说任何注释都是代码异味，描述性名称和简短的例程更具可读性，并且可以防止代码已更改但注释尚未更新的情况（这肯定让我感到一些遗留代码库）。我认为我不会走那么远，但是如果您可以编写不言自明的代码而无需额外解释，那似乎确实更可取。

所以，是的，基本上你说的。

于 2009-07-07T23:58:12.363 回答
6

XML 注释与其他注释略有不同。

如果设置正确，您可以让它们出现在 Visual Studio 的工具提示中，并使用它们创建带有 Sand Castle 的 MSDN 样式文档。我认为当您无法访问源代码时，他们应该告诉您他们在做什么。

关键是这些评论可以在没有他们评论的源代码的情况下出现。它们应该对另一个看不到您的代码并且不太关心您如何做事的开发人员有所帮助。

我不知道您正在使用的“Cop”工具，但如果有一种方法可以向打算将参数留空的工具发出信号，那就太好了。所以：

    /// <param name="fubar"></param>  // Haven't gotten around to it
    /// <param name="portNumber" />   // I intend this parameter to have no help

我从事过一些项目，我们必须填写所有内容，我们得到以下信息：

    /// <param name="portNumber">The Port Number</param> // What else could it be?

如果您不想使用上述功能，请继续关闭 Style Cop 规则。

于 2009-07-07T23:59:17.323 回答
2

完全同意，我在 StyleCop 中关闭的第一件事。如果您需要解释它，您已经以需要解释的方式命名它并且未能使代码自我记录。

于 2009-07-11T07:31:42.700 回答
2

对于那些仍然遇到这个问题的人，这篇文章how-to-change-a-stylecop-rule实际上有完美的答案。

于 2012-02-09T08:16:02.383 回答
1

您应该尝试GhosDoc是一种为应用程序中的每个代码成员自动生成文档的简单方法。只需安装它，右键单击成员并选择文档这个！

于 2010-01-25T01:47:49.237 回答
0

我认为这里的正确答案是“视情况而定”。您当然可以解释变量被标记为静态/常量的“原因”，或变量内容的业务逻辑/限制。话虽如此，我同意看到每个变量注释都会妨碍可读性，并且可能表明盲目遵循标准或不正确的命名。

于 2009-07-07T23:57:03.257 回答