我只是针对我的一些代码运行样式警察并获得了一些代码：
SA1600: The field must have a documentation header.
现在不要误会我的意思我喜欢风格警察，当你和一个以上的人一起开展一个项目时这很好，但这个规则对我来说似乎有些过分。你为什么要添加：
/// <summary>
/// blah blah blah
/// </summary>
到每个变量的顶部。我很确定我记得有人说（Martin Fowler，Kent Beck ......真的不记得ATM），评论应该说“为什么”而不是“什么”，我真的看不出你怎么能解释为什么变量。
我还发现对每个变量都有评论的代码难以阅读，因为你看到的只是绒毛。
我的想法是，如果你必须解释每个变量是什么，那么你在命名方面确实失败了。
是否有其他人发现评论变量有点代码味道或只是我。
答案 0 :(得分：20)
这是一篇相当古老的帖子，但在我自己寻找这个问题的解决方案时遇到了它，所以尽管我会提供解决方案。
如果您在规则编辑器中打开 Settings.StyleCop 文件，请选择文档规则节点，然后在详细设置部分中右侧取消选择包含字段选项。现在，您将不再需要记录字段。
答案 1 :(得分：12)
我不会说评论变量总是代码味道（并且听起来不像你所说的那样）。我同意评论每个变量，每一次都至少过度，并且可能表示命名不佳。实际上，有些人认为任何注释都是代码气味，描述性名称和简短例程更具可读性，可以防止代码更改的情况，但评论尚未更新（这肯定在一些遗留的代码库中咬了我一下。我认为我不会那么做，但是如果你能编写一些不言自明的代码而没有额外的解释，这似乎更合适。
所以是的，基本上就是你所说的。
答案 2 :(得分：6)
XML注释与其他注释略有不同。
如果您正确设置，可以将它们显示在Visual Studio中的工具提示中，并使用它们来创建Sand Castle的MSDN样式文档。我认为他们应该告诉你，当你无法访问源代码时，你正在做些什么。
关键是这些评论可以在没有他们评论的源代码的情况下出现。它们应该对另一个无法看到你的代码并且不关心你是如何做事的开发者有所帮助。
我不知道你正在使用的“警察”工具，但是有一种方法可以发信号通知工具打算留下一个参数。所以：
/// <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规则。
答案 3 :(得分：2)
完全同意并且我在StyleCop中关闭了第一件事。如果您需要解释它，您已经以一种需要解释的方式对其进行了命名，并且未能编写代码self documenting。
答案 4 :(得分：2)
对于那些仍然遇到过这个问题的人来说，这篇文章how-to-change-a-stylecop-rule实际上有完美的答案。
答案 5 :(得分：1)
您应该尝试GhosDoc是一种简单的方法，可以为您的应用程序上的每个代码成员自动生成文档。只需安装它，右键单击该成员并选择文档！
答案 6 :(得分：0)
我认为这里的正确答案是“这取决于”。您当然可以解释变量标记为static / const的变量的“原因”，或变量内容的业务逻辑/限制。话虽如此，我同意看到每个变量评论都会妨碍可读性，并且可能盲目地指示标准或不正确的命名。