该字段必须有文档标题 - 样式警察 - 代码气味？

Question

我只是针对我的一些代码运行样式警察并获得了一些:

SA1600: The field must have a documentation header.

现在不要误解我,我喜欢风格警察,当你与一个以上的人一起工作时,这很好,但这个规则对我来说似乎有些过分.你为什么要添加:

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

到每个变量的顶部.我很确定我记得有人说(Martin Fowler,Kent Beck ......真的不记得ATM),评论应该说"为什么"而不是"什么",我真的看不出你怎么能解释为什么变量.

我还发现对每个变量都有评论的代码难以阅读,因为你看到的只是绒毛.

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

有没有其他人发现评论变量有点代码味道或者只是我.

Answer 1

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

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

Answer 2

我不会说评论变量总是代码味道(并且它听起来不像你所说的那样).我同意评论每个变量,每一次都至少过度,并且可能表示命名不佳.事实上,有些人会争辩说任何评论都是代码味道,描述性名称和简短例程更具可读性并且可以防止代码被更改的情况,但是评论没有更新(这肯定会让我感到困惑)几个遗留代码库).我不认为我会把它拿得那么远,但是如果你能编写不言自明的代码而没有额外的解释,那似乎更可取.

所以,是的,基本上你说的.

Answer 3

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?

如果您不想使用上述功能,请继续关闭"样式警察"规则.