用 XML 注释记录 C# 代码的最佳实践是什么？答案

【问题标题】：What Are Best Practices For Documenting C# code with XML comments?用 XML 注释记录 C# 代码的最佳实践是什么？
【发布时间】：2011-03-09 18:29:20
【问题描述】：

我正在浏览我刚刚编写的一些新代码，并将 NDoc sytle cmets 添加到我的类和方法中。我希望能生成一个相当不错的 MSDN 风格的文档以供参考。

一般来说，在为类和方法编写 cmets 时，有哪些好的指导原则？ NDoc cmets 应该说什么？他们不应该说什么？

我发现自己正在查看 .NET 框架 cmets 所说的内容，但这很快就会过时；如果我可以有一些好的规则来指导自己，我可以更快地完成我的文档。

【问题讨论】：

标签： c# code-documentation ndoc

【解决方案1】：

在用于构建 API 文档的 cmets 中，您应该：

解释方法或属性的作用，它存在的原因，并解释任何对代码的普通使用者来说不言自明的领域概念。
列出参数的所有前提条件（不能为空，必须在一定范围内等）
列出所有可能影响调用者如何处理返回值的后置条件。
列出该方法可能抛出的任何异常（以及在什么情况下）。
如果存在类似的方法，请说明它们之间的区别。
提醒注意任何意外情况（例如修改全局状态）。
列举任何副作用，如果有的话。

【讨论】：

+1。我认为文档的主要关注点应该是公共接口，在生成外部文档（doxygen、NDoc 等）时更是如此。客户不需要知道你班级的每一个角落。不需要以这种格式记录实现细节；主要关注点应该是公共界面、它的使用方式、前置/后置条件以及 Jeff 指出的其他内容。
当然，公共接口应该有一致且有效的文档，但如果您的工作包括更新、修改或重写现有代码库，私有和受保护实体的文档非常有用。
但是你是怎么设计的呢？我在哪里可以找到清晰、有用的 XML 注释文档的好例子？我认为，这将是对这个答案的一个很好的补充。

【解决方案2】：

如果你最终得到的 cmets 没有任何价值，那就是浪费。

例如

/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)

...您完全没有添加任何价值，只是添加了更多代码来维护。

代码中经常充斥着这些多余的 cmets。

【讨论】：

是的，我知道 cmets 不能提供任何价值。这就是为什么我正在寻找有关确实提供价值的 cmets 的指南。
我认为这更像是一个糟糕的文档的例子，而不是一个不应该使用它的例子。公共方法可能应该有额外的文档，例如预期的异常、前置条件等。例如，当 action 为 null 时，该方法会做什么？
虽然我同意你关于多余 cmets 的话题，但多余的文档是另一回事。在某些情况下，您可能根本没有任何额外的文档，并且您的 xml 文档字符串只是方法名称的回声，但是我仍然添加了 docsctring - 部分原因是它确认该方法看起来很简单（而是比不费心记录该方法的人），但主要是因为如果它丢失了，它看起来只是错误。
我希望我能给这个答案投票 100 次。我认为这些 cmets 与我认为经过硬编码以始终成功的 UnitTest 相同。您已成功选中“我有 cmets”（或“我有单元测试”）框，但在任何方面都无法使代码更易于维护、更稳定或更好。

【解决方案3】：

StyleCop 提供代码和注释风格的提示。它给出的建议符合 MSDN 文档风格。

至于注释的内容，它应该为您的代码的用户提供足够的信息，让他们知道期望什么样的行为。它还应该回答用户可能遇到的潜在问题。因此，请尝试以对代码一无所知的人的身份使用您的代码，或者更好的是，请其他人这样做。

【讨论】：

我宁愿认为 StyleCop 是一个方便的提醒工具，用于在我从方法中添加/删除参数并间隔更新<params> 节点时使用。根据我上次演出的记忆，R# 的实时性太强了。
另一种选择：Resharper 在 UI 中执行此操作。

【解决方案4】：

对于属性，您的注释应指明该属性是只读、只写还是读写。如果您查看所有官方 MS 文档，属性 doc cmets 总是以“Gets ...”、“Gets or sets...”和（很少，通常避免只写属性）“Sets ...”开头。

【讨论】：

太棒了！对方法和类有什么想法吗？
老实说，唯一认真对待 doc cmets 的公司是 Microsoft :) 我只是浏览他们的 cmets 并了解他们是如何做的。他们肯定有关于如何格式化 cmets 以及应该说什么的标准。 MS 还可以很好地指示方法抛出的异常。可悲的是，doc cmets 最终被用作修复 C# 语言 IMO 中的小问题的创可贴（比如依靠注释或编译器错误来确定属性是否为只读，这让我很恼火）
我非常重视 doc cmets，我不为 Microsoft 工作。在良好的文档 cmets、GhostDoc 和 Sandcastle/Sandcastle Help File Builder 之间，我们的核心库有一个网站开发人员可以参考。我真的不喜欢通过单步执行代码而不是阅读简洁的文档来直觉地使用方法/属性。

【解决方案5】：

不要忘记什么是有效的 XML。例如：

/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>

（错误：无效的 XML）。

【讨论】：

【解决方案6】：

我写了

注释以包含我想知道的信息，如果我是调用该函数（或实例化该类）的人。

我写了注释来包含我想知道的信息，如果我的任务是调试或增强那个函数或类。注意：这并不能取代对良好内联 cmets 的需求。但有时对函数/类内部工作原理的总体概述非常有帮助。

【讨论】：

【解决方案7】：

正如MSDN page 中所述，您使用 XML 文档 cmets 自动生成文档，因此如果您正在编写 API 并且不想在代码和文档上重复工作，那么它是有意义的，还有额外的好处使它们保持同步 - 每次更改代码时，都会修改相应的 cmets 并重新生成文档。

使用/doc编译，编译器会搜索源代码中的所有XML标签并创建一个XML文档文件，然后使用Sandcastle等工具生成完整的文档。

【讨论】：

我不明白 XML 文档的好处和方法。我需要一点帮助，了解人们在这些 cmets 中真正发现的有用之处。
@Esteban Araya 正如我所说，接近您正在记录的实际代码，允许您在现场记录更改，而无需切换到另一个应用程序并搜索适当的位置修改。

【解决方案8】：

关于 cmets 的一件事是更新它们。太多人更改了功能，但没有更改评论以反映更改。

【讨论】：

是的。我们过去通过将其作为标准代码审查清单的一部分对此进行了补救。