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

我正在浏览我刚刚编写的一些新代码，并将NDoc sytle注释添加到我的类和方法中。我希望生成一个很好的MSDN风格的文档供参考

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

---

我发现自己在看.NETFramework的评论，但这很快就过时了；如果我能有一些好的规则来指导我自己，我可以更快地完成我的文档。

如果你最后的评论没有任何价值，那就是浪费

比如说

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

//
///获取管理员对操作的批准
/// 
///要获得批准的操作对象
公共无效GetManagerApprovalFor（操作）

…您完全没有添加任何价值，只是添加了更多要维护的代码

---

代码中经常会出现这些多余的注释。

对于属性，您的注释应该指明该属性是只读、只读还是读写。如果查看所有官方MS文档，属性文档注释总是以“获取…”、“获取或设置…”开头，并且（很少，通常避免只写属性）“设置…”

如上所述，您使用XML文档注释自动生成文档，因此，如果您正在编写一个API，并且不想在代码和文档两个方面同时工作两次，那么它就很有意义了，这还带来了保持它们同步的额外好处——每次更改代码时，您都会修改相应的注释并重新生成文档

---

使用

/doc

编译，编译器将搜索源代码中的所有XML标记并创建一个XML文档文件，然后使用诸如生成完整文档之类的工具。

注释的一件事就是更新它们。太多的人修改了一个函数，然后不更改注释以反映更改。

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

• 解释方法或属性的作用、它存在的原因，并解释对代码的普通使用者来说不明显的任何领域概念

• 列出参数的所有前提条件（不能为null，必须在一定范围内，等等）

• 列出可能影响调用者如何处理返回值的任何后置条件

• 列出该方法可能抛出的任何异常（以及在什么情况下）

• 如果存在类似的方法，请解释它们之间的差异

• 提醒注意任何意外情况（例如修改全局状态）

• 列举任何副作用（如果有）

提供代码和注释风格提示。它给出的建议与MSDN文档风格一致
至于注释的内容，它应该为代码的用户提供足够的信息，让他们知道预期的行为是什么。它还应该回答用户可能遇到的潜在问题。因此，请尝试将您的代码用作对代码一无所知的人，或者更好的做法是，请其他人这样做。
我写注释是为了包含我想知道的信息，即我是否是调用该函数（或实例化该类）的人

---

我写评论是为了包含我想知道的信息，如果我被指派调试或增强该函数或类。注意：这并不能取代对好的内联注释的需求。但有时，对函数/类的内部工作原理的一般概述非常有用。
不要忘记什么是有效的XML。例如：

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

//
///如果用户数>1000，则触发事件
/// 

---

（错误：无效XML）。
是的，我理解注释不能提供任何值。这就是为什么我在寻找关于提供价值的评论的指南。我认为这更多的是一个糟糕文档的例子，而不是一个不应该使用它的例子。公共方法可能应该有额外的文档，例如预期的异常、前提条件等。例如，当操作为空时，该方法会做什么？尽管我同意你关于超级注释的观点，但超级文档是另一回事。在某些情况下，您可能只是没有额外的文档，而xml文档字符串只是方法名称的一个回音，但是我仍然添加了docsctring-部分原因是它确认了该方法与看起来一样简单（而不是有人懒得记录该方法），但主要是因为如果它不见了，看起来就错了。我希望我能把这个答案投上100次。我将这些评论视为一个单元测试，它被硬编码为总是成功的。您已经成功地选中了“我有评论”（或“我有单元测试”）框，但完全没有使代码更易于维护、更稳定，或者在任何方面都更好。太好了！对方法和类有什么想法吗？老实说，唯一认真对待文档评论的公司是微软：）我只是浏览他们的评论，了解他们是如何做的。他们对评论的格式和内容都有明确的标准。MS还很好地指示了方法抛出的异常。可悲的是，文档注释最终被用作修复C#语言IMO中的小问题的创可贴（比如依赖注释或编译器错误来确定属性是否为只读，这让我很恼火）。我认真对待文档注释，我不为Microsoft工作。在良好的文档评论、GhostDoc和Sandcastle/Sandcastle帮助文件生成器之间，我们的核心库有一个网站供开发者参考。我真的不喜欢通过单步执行代码而不是阅读简明的文档来直观地使用方法/属性。我不理解XML文档的好处和方法。我需要一点帮助，看看人们在这些评论中发现了什么有用的东西。@estebana