我正在浏览我刚刚编写的一些新代码，并将 NDoc 样式注释添加到我的类和方法中。我希望生成一个非常好的 MSDN 样式文档以供参考。
一般来说，在为类和方法编写注释时，有哪些好的指导方针？NDoc 评论应该说什么？他们不应该说什么？
我发现自己在看 .NET 框架评论说什么，但这很快就过时了；如果我可以有一些好的规则来指导自己，我可以更快地完成我的文档。
问问题
26032 次
8 回答
58
在用于构建 API 文档的注释中，您应该：
解释方法或属性的作用，它存在的原因，并解释任何对代码的普通使用者来说不是不言而喻的领域概念。
列出参数的所有前提条件（不能为空，必须在一定范围内等）
列出任何可能影响调用者如何处理返回值的后置条件。
列出该方法可能抛出的任何异常（以及在什么情况下）。
如果存在类似的方法，请解释它们之间的区别。
提醒注意任何意外情况（例如修改全局状态）。
列举任何副作用，如果有的话。
于 2010-06-29T17:58:55.253 回答
17
如果您最终得到的评论没有增加任何价值，那只是浪费。
例如
/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)
...您绝对没有添加任何价值，只是添加了更多代码来维护。
代码中经常充斥着这些多余的注释。
于 2010-06-29T17:51:08.590 回答
6
StyleCop提供代码和注释风格的提示。它给出的建议符合 MSDN 文档风格。
至于注释的内容，它应该为您的代码的用户提供足够的信息，让他们知道期望什么样的行为。它还应该回答用户可能遇到的潜在问题。因此，请尝试以对代码一无所知的人的身份使用您的代码，或者更好的是，请其他人这样做。
于 2010-06-29T18:03:06.090 回答
5
对于属性，您的注释应指明该属性是只读、只写还是读写。如果您查看所有官方 MS 文档，属性文档注释总是以“Gets ...”、“Gets or sets...”和（很少，通常避免只写属性）“Sets ...”开头
于 2010-06-29T17:51:48.090 回答
5
不要忘记什么是有效的 XML。例如：
/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>
（错误：无效的 XML）。
于 2010-06-29T21:24:42.703 回答
3
我写了 <summary> 注释以包含我想知道的信息，如果我是调用该函数（或实例化该类）的人。
我写了 <remarks> 注释来包含我想知道我是否负责调试或增强该函数或类的信息。注意：这并不能取代对良好内联注释的需求。但有时对函数/类内部工作原理的一般概述非常有帮助。
于 2010-06-29T21:19:44.520 回答
0
如MSDN 页面所述，您使用 XML 文档注释自动生成文档，因此如果您正在编写 API 并且不想在代码和文档中重复工作，那么将它们保留在同步 - 每次更改代码时，都会修改相应的注释并重新生成文档。
编译使用/doc，编译器将搜索源代码中的所有 XML 标签并创建一个 XML 文档文件，然后使用Sandcastle等工具生成完整的文档。
于 2010-06-29T17:57:39.317 回答
0
关于评论的一件事是更新它们。太多人更改功能然后不更改评论以反映更改。
于 2010-06-29T17:58:46.860 回答