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

StackOverflow https://stackoverflow.com/questions/3143324

  •  01-10-2019
  •  | 
  •  

题

我正在浏览一些我刚刚编写的新代码，并在我的课程和方法中添加了NDOC Sytle评论。我希望生成一个很好的MSDN样式文档以供参考。

通常，在为班级和方法编写评论时，有什么好的准则？ NDOC评论应该怎么说？他们不应该说什么？

我发现自己看着.NET框架的评论说了什么，但这很快就变老了。如果我可以有一些好的指导自己的规则，那么我可以更快地完成文档。

有帮助吗？

解决方案

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

  • 解释该方法或属性的作用，为什么根本存在，并解释您代码中普通消费者不认为的任何域概念。

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

  • 列出任何可能影响呼叫者处理退货值的后条件。

  • 列出该方法可能会抛出的任何例外（在什么情况下）。

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

  • 引起注意任何意外的事情（例如修改全球状态）。

  • 如果有的话，列举任何副作用。

其他提示

如果您最终得到不会增加任何价值的评论，那么它们只是浪费。

例如

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

...您绝对没有任何价值，只是添加了更多代码以维护。

这些多余的评论常常会散布代码。

Stylecop 提供代码的提示 和 评论风格。它给出的建议符合MSDN文档样式。

至于评论的内容，它应该为您的代码提供足够的信息，以了解期望什么样的行为。它还应该回答用户可能遇到的潜在问题。因此，尝试将您的代码用作对代码一无所知的人，甚至更好，请其他人这样做。

对于属性，您的评论应指示是否仅读取属性，仅写或读写。如果您查看所有官方MS文档，属性文档注释始终以“ get ...”，“ get or sets ...”开始，并且（很少，避免通常仅写属性）“设置...”

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

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

（错误：无效XML）。

我写的u003Csummary>评论以包括我想知道的信息是我是一个呼叫该功能（或实例化该类）的信息。

我写的u003Cremarks>评论以包括我想知道的信息，即我是否负责调试或增强该功能或类。注意：这并不能取代对良好的内联评论的需求。但是有时对功能/类内部工作的一般概述非常有帮助。

如 MSDN页面, ，您使用XML文档注释自动生成文档，因此，它可以感觉到，如果您正在编写API并且不想在代码和文档上两次工作，则每次更改时都可以使它们保持同步。代码，您可以修改适当的注释并重新生成文档。

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

关于评论的一件事是更新它们。太多的人更改功能，然后不要更改评论以反映变化。

许可以下： CC-BY-SA 和 归因
不隶属于 StackOverflow
scroll top