XML评论：要用还是不用？

Question

我的同事很少（如果有的话）在使用我们的软件时使用XML注释（我不能说我更好）。我最近看到了使用它们的好处，但是如果它们正在记录的代码是清晰写入的（表达性/描述性变量/函数名称，一些在线评论），它们真的值得吗？

谢谢！

Answer 1

XML注释对于生成文档非常有用。如果代码写得很清楚，那么你就不需要评论来帮助你理解代码。

然而，文档注释对类的用户来说是有用的，因为它（应该）包含对类或方法功能的描述，而不是对代码的描述。

Answer 2

XML注释对于API甚至那些在小组中使用的API都非常有用。

Answer 3

我们发现它很有用，因为vs自动检查以确保某些评论在那里。此外，任何新进入组织的人都知道评论如何工作，我们不必解释一个新的评论代码体系。有时我们已经从中生成了文档，但是对我们来说使用它真的更容易，因为它为您填充了很多东西（如某些参数标签等）

Answer 4

就内部代码和注释而言， here's a post由Jeffery Palermo我刚刚阅读并且必须同意。

总结：许多评论只是减少了可读性，并且帮助不大，良好的评论可能会非常有用，但会增加维护软件的成本，甚至会在维护和提供虚假信息时导致严重问题。没有任何设计和命名代码的替代品。

Answer 5

是不是有一个注释标记在功能上被忽略，但可以通过一些XSLT进行处理直接转换为文档？评论是好的（我使用它们），但我认为注释标记的价值和直接转换它可以超过使用注释作为文档。因此，总之，使用注释标签作为文档被他人阅读，使用注释来注释你自己或'幕后'的东西（即'OMG FIX THIS BEFORE THE WORLD EXPLODES！'）

Answer 6

我认为代码评论非常重要，特别是在面向公众的方法和特性方面。除非他知道他可能不知道它的目的的方法的情况下

Linker.Extract(IpoValidator validator, MeanDexIndicator Indicator) 

：人们可能意味着良好时，他们说他们的代码是描述性的，也许是这样，但想到新来的家伙谁看这个的。人们似乎对评论的主要问题是他们不是很有帮助。这是因为人们写了不好的评论。你应该谈论发生了什么，而不是它是什么。我可以看到这种方法是一种提取方法，所以评论如下：

<Summary>Extracts The Fumble <\Summary> 

是浪费能源。以下更好：

<Summary> 
The Fumble needs to be extracted before the bopper can be used. In order for 
extraction to work a validator and indicator need to be provided. Once extracted 
the bopper is available in the property Linker.Bopper. On fail this 
method will raise the CrappedOutException. 
</Summary> 

看到区别？

我倾向于只使用摘要参数和回报，因为它们都显示在intellisense中，其他所有内容都像评论一样，可能会浪费时间，因为它们并不总是显示。

至于那个在改变一些东西后拒绝更新他的评论的人。代码评论应该抓住这一点。我个人使用私人方法和道具两个XML评论，但那是个人选择。在公众面前的方法和属性？我不是可选的。