Coding style 该字段必须具有文档头样式的Cop代码气味？

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

SA1600: The field must have a documentation header.

别误会，我喜欢时尚警察，当你和一个以上的人一起做一个项目时，这很好，但这条规则对我来说有点过分。为什么要添加：

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

//
///废话废话
/// 

到每个变量的顶部。我很确定我记得有人说过（马丁·福勒，肯特·贝克..我真的不记得ATM机了）那句话应该是“为什么”而不是“什么”，我真的不知道如何解释变量的原因

我还发现对每个变量都有注释的代码更难阅读，因为您看到的都是模糊的

我的想法是，如果你必须解释每个变量是什么，那么你在命名方面就真的失败了

---

其他人是否觉得注释变量有点代码味道，还是只有我一个人。

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

我不会说注释变量总是一种代码味道（听起来也不像你说的那样）。我确实同意，评论每一个变量，每一次，至少是过度的，并且可能表明命名不好。事实上，有些人会认为任何注释都是一种代码味道，描述性名称和简短例程更具可读性，可以防止代码被更改，但注释没有被更新（这肯定会让我在一些遗留代码库中感到痛苦）。我不认为我会走得太远，但是如果你能写一些不需要额外解释的自解释代码，那就更好了

---

是的，基本上就是你说的。

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

如果设置正确，可以将它们显示在VisualStudio的工具提示中，并使用它们使用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?

///端口号//可能是什么？

---

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

完全同意，我在StyleCop中关闭的第一项功能。如果您需要解释它，那么您已经以一种需要解释的方式命名了它，并且在生成代码时失败了。

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

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

---

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

对于那些仍然遇到这个问题的人，这篇文章实际上有一个完美的答案。

是的，我在公共方法上经常使用XML，但对我来说，用XML注释私有变量似乎是不必要的混乱。很好，但是应该注意的是，这只适用于字段，并不能解决属性问题。是的，为什么不直接点击所有你不同意的项目，直到StyleCop与你编写的代码兼容。这是最简单的方法。罗伯特·C·马丁在他的《清洁代码》一书中提到了这些问题。他有一个有趣的东西。你认为自我评论是非常不同的，我，这个家伙，从六个月后开始阅读你的代码，会考虑自我评论。如果注释与代码不匹配，则修复注释。根据定义，GhosDoc只能添加已经可以从代码（即变量类型和名称）派生的“文档”。因此，它会生成无用的文档（几乎按定义）；它不会告诉您任何您无法从代码中确定的内容。这只是增加了多余的噪音。鲍勃·马丁说“评论总是失败的”（emp.added）-抄送，第4章，第页。54因此，鉴于此StyleCop规则要求在所有这些地方都有注释（假设您处理所有警告，并且您应该这样做，因为它们是用来帮助您编写好代码的），根据Bob叔叔的说法，此规则无效。如果一个评论，这是一个必要的邪恶的罕见事件，成为必要的，你作为开发人员会知道，所以你会添加它。在这种情况下，关于xml格式的规则是一件好事，因此我保留了除1600-02161116151618之外的所有规则，以缓解他提到的一些问题。