Question

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

谢谢！

Answer 1

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

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

Answer 2

我认为代码注释非常重要，尤其是面向公众的方法和属性。当人们说他们的代码是描述性的时候可能意味着很好，也许就是这样，但想想那个看着这个代码的新人：

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评论两个，但那个是个人选择。面向公众的方法和财产？我不是可选的。

Answer 3

XML注释对于API，即使是在小组中使用的API也非常有用。

Answer 4

我们发现它很有用，因为vs会自动检查以确保存在某些注释。此外，任何刚进入组织使用过vs的人都知道评论是如何工作的，我们不必解释一个新的评论代码系统。有时候我们会从中生成文档，但实际上我们更容易使用它，因为它为你填充了许多东西（比如一些参数标签等）。

Answer 5

至于内部代码和评论，here's a post Jeffery Palermo我刚刚阅读并且必须同意。

总结：很多评论只是降低了可读性并且帮助很少，好的评论可能非常有用，但增加了维护软件的成本，甚至可能在没有维护时提出重大问题并提供虚假信息。精心设计和命名的代码是无可替代的。

Answer 6

是否存在功能上被忽略的注释标记，但某些XSLT可以将其直接转换为文档？评论是好的（我使用它们）但我认为注释标记的价值和直接转换它可以做到超过评论作为文档的使用。总而言之，使用注释标签来让他人阅读文档，使用注释来记录自己的注释或“幕后”的东西（即“OMG在世界爆炸之前修复它！”）

XML注释：使用或不使用？

6 个答案: