C# 编程的 XML 注释技巧 [关闭]

Question

早上好、下午好、晚上好或晚上好（取决于您所在的时区）。

这只是关于 C# 中 XML 注释的一般问题。我从来没有热衷于评论我的程序，我一直都是一个详细的变量/属性/方法命名者，并让代码自己说话。如果我正在编写一些相当混乱的代码，我确实会写注释，但大多数情况下我不会写很多注释。

我正在阅读一些关于 .NET、Sandcastle 中的 XML 注释以及 Codeplex 上的帮助文件生成器的文章，它让我走上了想要记录我的代码并为那些必须深入研究我的代码的人生成一些漂亮、有用的文档的道路。当我不再在这里时编码。

我的问题是关于标准和惯例。有“良好”XML 注释指南吗？您应该注释每个变量和属性吗？每种方法？我基本上只是在寻找有关如何编写好的注释的技巧，这些注释将由 sandcastle 编译成好的文档，这样其他程序员在最终不得不处理我的代码时就不会咒骂我的名字。

提前感谢您的意见和建议， 斯科特·韦尔库斯基

Answer 1

就个人而言，我们确保每个公共和受保护的方法都有 XML 注释。它还将为您提供智能感知，而不仅仅是最终用户帮助文档。过去，我们也将其包含在私有作用域声明中，但并不认为这是 100% 必需的，只要方法简短且切题即可。

不要忘记有一些工具可以让您更轻松地执行 XML 注释任务：

• 幽灵文档 - 注释继承和模板插件。
• Sandcastle 帮助文件生成器 - 通过 GUI 编辑 Sandcastle 项目，可以从命令行运行（用于构建自动化），并且可以编辑 MAML 以获取不是从代码派生的帮助主题。（1.8.0.0 alpha 版本非常稳定并且改进很大。已经使用了大约一个月了，1.7.0.0以上）

Answer 2

注释非常经常是过时的。这一直是个问题。我的经验法则：你必须努力更新评论越多，速度越快的评论将被淘汰。

XML注释是伟大的API开发。他们工作得很好用Intellisens，他们可以让你产生在任何时间的HTML帮助文档。

但是，这不是免费的：维护他们的将是硬的（看任何非简单的例子，你就会明白我的意思），所以他们往往会被很快过时。其结果是，审查XML注释应添加到您的代码审查作为强制性检查并该检查应每一个文件更新时进行。

好，因为它是昂贵的维护，因为很多非专用符号的（在非API开发）由1个或2类只使用的，并且由于这些symboles往往不言自明的，我绝不会执行一个治说，每个非专用符号应该是XML注释。的这将是矫枉过正和conterproductive 即可。你将得到的是什么，我在很多地方看到：几乎是空的XML注释添加无关的symbole名。和代码只是一个小的可读性...

我觉得非常，非常重要指南，了解有关意见在正常（非API）的代码行不应该是如何，他们应该写成但是关于<强> WHAT它们应包含即可。许多开发者仍然不知道的写什么。对应当怎么评价，结合实例，会做你的代码不仅仅是一个普通的更好的描述：“做每一个非私有symbole使用XML注释。”

Answer 3

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

我不记录专用或内部部件或内部的类。因此变量（我想你的意思领域），因为它们是私有的。

的目的是创建用于谁没有对源代码准备访问的显影剂一些文档。

奋进放置一些实例中，其中使用不明显。

Answer 4

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

一般来说，我努力尝试有意义的注释添加到所有的公共/ protected成员，这是很方便的，因为如果你建立时打开XML注释，你丢失的评论自动警告。根据不同的复杂性，可能是我填写的每一个细节 - 即如果是100％，明显是每个参数的的的做（即不存在特殊的逻辑，而且只有1解释的逻辑方法变量），然后我的可能的偷懒而不是有关参数添加注释。

但我肯定试图描述什么样的方法，种类，性质等代表/做。

Answer 5

我们记录的公共方法/属性/等我们的图书馆。作为构建过程的一部分，我们使用NDoc的创建MSDN般的Web引用。它已经为快速参考和查找非常有益的。

这也是伟大的智能感知，尤其是与新的团队成员，或者像你说的，当原作者已经一去不复返了。

我同意代码，一般来说，应该是不言自明的。该XML机制的文档，对我来说，更多的是参考和查找时你没有源开放。

Answer 6

我个人的意见是，以避免评论。评论是很危险的。因为在业内，我们随时更新的代码（因为业务和需求总是在不断变化），但很少改变我们更新我们的看法。这可能误导的程序员。