c# - C# 编程的 XML 注释技巧

<分区>

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

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

我正在阅读有关 .NET、SandcaSTLe 和 codeplex 上的帮助文件生成器中的 XML 注释的一些资料，它让我走上了想要记录我的代码并为那些必须的人生成一些有用的文档的道路在我不在时深入研究我的代码。

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

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

最佳答案

就个人而言，我们确保每个公共(public)和 protected 方法都有 XML 注释。它还将为您提供 Intellisense，而不仅仅是最终用户帮助文档。过去，我们也将它包含在私有(private)范围声明中，但并不认为它是 100% 必需的，只要方法简短且切中要害即可。

不要忘记，有一些工具可以让您更轻松地完成 XML 注释任务:

GhostDoc - 注释继承和模板加载项。
Sandcastle Help File Builder - 通过 GUI 编辑 SandcaSTLe 项目，可以从命令行运行(用于构建自动化)，并且可以编辑 MAML 以获得不是从代码派生的帮助主题。 (1.8.0.0 alpha版本非常稳定，改进也非常多，到现在已经用了一个月左右，超过1.7.0.0)

关于c# - C# 编程的 XML 注释技巧，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/355957/

相关文章：

c# - 为 C# 解决方案生成 sandcaSTLe 文档