方法摘要XML注释的良好实践

Question

我最近在程序的顶部使用了方法摘要XML Comments,并且想知道是否存在与此相关的任何逻辑或良好实践.

我从未在评论中添加任何内容,因为我将方法的描述放在摘要标记中.什么属于摘要,什么属于备注？

我很少在返回标记中放置任何内容,因为它似乎是多余的,因为我通常会解释摘要中返回的内容.我应该简单地保留返回标记中返回的对象类型吗？

任何人都可以建议这些XML注释的良好,逻辑或常用方法对团队中的其他程序员有益,同时不要求多次显示相同的信息吗？

Answer 1

我最常用的标签是:

• <summary>- 带有<see>标记的方法/类/成员的用途
• <param name="paramName"> - 什么是参数
• <returns> - 该方法返回什么
• <see cref="referenceToMember"/> - 允许链接以引用另一个类/成员(非常适合在构造函数中使用)
• <exception cref="referenceToMember"/> - 引用该方法抛出的异常
• <example> <code>... - 如果您想举例说明该方法的用法
• <value> - 描述属性值
• <c>- 描述代码段(可以与之一起使用<returns>)
  

例子

• <summary> 同 <see cref=".."/>

  /// <summary>
  /// Initializes a new instance of the <see cref="Form1"/> class.
  /// 
  public Form1()
  {
     InitializeComponent();
  }

• <returns> 同 <c>

  /// <summary>
  /// Validates the date.
  /// </summary>
  /// <param name="date">The date.
  /// <returns><c>true</c> if the date is valid; otherwise <c>false</c>.</returns>
  public bool validateDate(string date)
  {
      // Do something
  }

自动标记生成

您也可以使用免费的Visual Studio插件(如Ghost Doc)生成所需的标记,而不是尝试手动插入这些标记.

xml标记的使用

除了在API(或开发人员帮助文档)中提供信息之外,它还允许成员的用户获取重要信息,例如exception方法可以抛出的类型.我引用这个例子,因为知道exceptionhelper/model类可以抛出哪些类型非常有用.然后,视图/控制器类只能捕获那些异常并处理它们.

Answer 2

在我看来，您是正确的，<summary> 可能是您最常使用的标签来解释您的方法究竟要做什么。但是，如果您的方法有好的、有用的名称，那么预计大多数开发人员会使用它来对方法的行为方式做出一些假设。例如，他们假设调用“GetName”可能没有副作用，并返回实例的名称，而不管注释说什么。

考虑到这一点，我倾向于将我的评论集中在我知道的任何“问题”上，而不是写关于该方法应该做什么的段落，知道如果有人使用我的代码，并且它不会按照他们的方式工作认为应该，他们要做的第一件事就是查看文档，希望得到一些指导。下面是我如何使用各种标签的几个例子。

• <returns>- 指示返回值可能为空。描述返回null与返回之间的语义差异string.Empty
  
• <remarks>- 非常适合解释“陷阱”，例如“阅读器必须处于就绪状态，并且光标位于正确的位置才能开始阅读。调用者负责在此方法完成后关闭阅读器。” 我通常会在对 API 大惊小怪半小时之后根据需要添加这些注释，然后才意识到一些不明显的愚蠢细节。
  
• <example>- 好的 API 应该易于使用，但有时您无能为力。这是伟大的的方法是如何提供指导打算使用（虽然你不能保证它是如何会被使用）。请参阅下面的示例。

<example>
var token = m_caller.GetAuthToken();
var result = m_caller.Call(method, token);
</example>

我敢肯定还有数百个其他例子我可以梦想，但我希望这有助于让你指向正确的方向！