我正在编写一些我刚编写的新代码，并将NDoc sytle注释添加到我的类和方法中。我希望能够生成一个非常好的MSDN样式文档供参考。
一般来说，为类和方法编写注释时有哪些好的指导原则？ NDoc评论应该说什么？他们应该怎么说？
我发现自己正在研究.NET框架评论所说的内容，但这种情况会变得很快;如果我能有一些好的规则来指导自己，我可以更快地完成我的文档。
答案 0 :(得分：53)
在用于构建API文档的注释中，您应该：
解释方法或属性的作用，为什么存在，并解释任何对代码的普通使用者不言自明的域概念。
列出参数的所有前提条件（不能为空，必须在一定范围内等）。
列出可能影响来电者如何处理返回值的任何后置条件。
列出方法可能抛出的任何异常（以及在什么情况下）。
如果存在类似的方法，请解释它们之间的差异。
提醒您注意任何意外情况（例如修改全局状态）。
列举任何副作用，如果有的话。
答案 1 :(得分：16)
如果您最终得到的评论不会增加任何价值，那么这些评论就会浪费。
例如
/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)
...你绝对没有添加任何价值，只是添加了更多代码来维护。
很多代码都充斥着这些多余的评论。
答案 2 :(得分：6)
StyleCop提供代码和评论样式的提示。它提供的建议符合MSDN文档样式。
对于评论的内容，它应该为您的代码的用户提供足够的信息，说明期望的行为类型。它还应该回答用户可能遇到的潜在问题。因此，请尝试将您的代码用作对代码一无所知的人，或者更好，请其他人这样做。
答案 3 :(得分：5)
对于属性，您的注释应指示属性是只读还是只写还是读写。如果你查看所有正式的MS文档，属性文档注释总是以“获取...”，“获取或设置...”开头，并且（很少，通常避免只写属性）“集合......”
答案 4 :(得分：5)
不要忘记什么是有效的XML。例如：
/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>
（错误：XML无效）。
答案 5 :(得分：2)
我写了＆lt; summary＆gt;如果我是调用该函数的那个（或实例化该类），请注释以包含我想知道的信息。
我写了＆lt;备注＆gt;如果我负责调试或增强该功能或类的任务，请评论以包含我想知道的信息。注意：这并不能取代良好的内联注释。但有时候对函数/类的内部工作方式的一般概述非常有帮助。
答案 6 :(得分：0)
正如MSDN page所述，您使用XML文档注释自动生成文档，因此制造商会感觉您是在编写API而不想在代码和文档中使用两次，保持同步的好处 - 每次更改代码时，都可以修改相应的注释并重新生成文档。
使用/doc进行编译，编译器将搜索源代码中的所有XML标记并创建XML文档文件，然后使用Sandcastle等工具生成完整的文档。
答案 7 :(得分：0)
关于评论的一点是更新它们。太多人改变功能然后不改变评论以反映变化。