用于C＃编程的XML注释技巧

Question

早上好，下午，晚上或晚上（取决于你的时区）。

这只是关于C＃中XML注释的一般问题。我从来没有对评论我的程序做过很大的贡献，我一直都是一个冗长的变量/属性/方法名称，让代码说明一切。如果我编写的内容相当令人困惑，我会写评论，但在大多数情况下我不会写很多评论。

我正在阅读.NET，Sandcastle和codeplex上的帮助文件构建器中的XML注释，它让我想要记录我的代码并为那些必须的人生成一些很好的，有用的文档。当我不在这里时，深入研究我的代码。

我的问题是关于标准和惯例。是否有“好”XML评论指南？你应该评论每个变量和属性吗？每个方法？我只是在寻找有关如何编写好的注释的提示，这些注释将由sandcastle编译成好的文档，以便其他程序员在最终不得不处理我的代码时不会诅咒我的名字。

提前感谢您的意见和建议， Scott Vercuski

Answer 1

就个人而言，我们确保每个公共和受保护的方法都有XML注释。它还将为您提供Intellisense，而不仅仅是最终用户帮助文档。在过去，我们也将它包含在私有范围的声明中，但不要觉得它是100％要求的，只要这些方法很短且在点上。

不要忘记有一些工具可以让您轻松完成XML评论任务：

• GhostDoc - 评论继承和模板加载项。
• Sandcastle Help File Builder - 通过GUI编辑Sandcastle项目，可以从命令行运行（用于构建自动化），并可以编辑MAML以获取不是从代码派生的帮助主题。 （1.8.0.0 alpha版本非常稳定且非常好。现在已经使用了大约一个月，超过1.7.0.0）

Answer 2

评论经常过时。这一直是个问题。我的经验法则：您需要做的更新评论越多，评论就越快过时。

XML注释非常适合API开发。它们可以很好地与Intellisens配合使用，它们可以让您立即生成HTML帮助文档。

但这不是免费的：维护它们会很难（看看任何非平凡的例子，你会明白我的意思），所以它们会很快过时。因此，审核XML注释应作为强制检查添加到您的代码审核中，并且每次更新文件时都应执行此检查。

好吧，因为维护成本很高，因为很多非私有符号（在非API开发中）只使用1或2个类，并且因为这些符号通常是不言自明的，所以我永远不会强制执行规则说每个非私有符号应该是XML注释。 这将是一种过度杀伤和刺激性的。你会得到的是我在很多地方看到的：几乎空的XML注释没有为symbole名称添加任何内容。而且代码的可读性稍差......

我认为关于普通（非API）代码中的注释的非常非常重要指南不应该是关于如何编写而是关于他们应该包含什么。许多开发人员仍然不知道写什么。使用示例对应该注释的内容的描述对于代码而言只会比普通代码更好：“在每个非私有符号上使用XML注释。”。

Answer 3

我记录公共类和这些类的公共/受保护成员。

我没有记录私人或内部成员或内部类。因此变量（我认为你的意思是字段）因为它们是私有的。

目标是为没有现成的源代码访问权限的开发人员创建一些文档。

努力提供一些使用不明显的例子。

Answer 4

我很少评论方法变量，同样很少评论字段（因为它们通常由属性覆盖，或者如果使用自动实现的属性则根本不存在）。

通常我会努力为所有公共/受保护成员添加有意义的注释，这很方便，因为如果在构建期间打开xml注释，则会收到缺少注释的自动警告。根据复杂程度，我可能不会填写每一个细节 - 即，如果每个参数有可以100％明显（即没有特殊逻辑，并且只有一种逻辑解释方式）变量），然后我可能变得懒惰而不添加关于参数的注释。

但我当然试图描述代表/做什么方法，类型，属性等。

Answer 5

我们在库中记录公共方法/属性/等。作为构建过程的一部分，我们使用NDoc创建类似MSDN的Web引用。它对快速参考和查找非常有帮助。

这对Intellisense来说也很棒，特别是对于新的团队成员，或者就像你说的那样，当原作者离开时。

我同意代码一般应该是不言自明的。对我来说，XML文档更多的是关于没有源打开时的引用和查找。

Answer 6

就我个人而言，我的意见是避免评论。评论很危险。因为在行业中我们总是更新代码（因为业务和需求总是在变化），但我们很少更新我们的评论。这可能会误导程序员。