2

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

谢谢！

4

6 回答 6

5

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

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

于 2009-01-19T15:24:38.270 回答
1

我认为代码注释非常重要，尤其是在面向公众的方法和属性方面。当人们说他们的代码是描述性的时，他们可能是善意的，也许确实如此，但想想看这个的新人：

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>

看到不同？

我倾向于只使用摘要参数和返回，因为它们都以智能感知显示，其他所有内容都像评论一样，并且可能会浪费时间，因为它们并不总是显示出来。

至于在更改某些内容后拒绝更新评论的人。代码审查应该抓住这一点。就我个人而言，我对私有方法和道具两个使用 xml 注释，但那一个是个人选择。关于面向公众的方法和属性？我是非可选的。

于 2011-07-01T21:28:39.117 回答
0

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

于 2009-01-19T15:27:09.873 回答
0

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

于 2009-01-19T15:27:21.073 回答
0

就内部代码和评论而言，这是Jeffery Palermo的一篇文章，我刚刚阅读并同意。

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

于 2009-01-19T15:41:41.513 回答
0

是否存在在功能上被忽略但可以由某些 XSLT 处理以直接转换为文档的注释标记？注释很好（我使用它们），但我认为注释标签的价值和它的直接转换可以胜过将注释用作文档。因此，总而言之，使用注释标签作为其他人阅读的文档，使用注释作为自己的注释或“幕后”的东西（即，“天哪，在世界爆炸之前解决这个问题！”）

于 2009-01-19T16:36:34.630 回答