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

我最近一直在我的过程顶部使用方法摘要XML注释，我想知道是否有与此相关的逻辑或良好实践

我从不在备注中添加任何内容，因为我将方法的描述放在summary标记中。什么属于摘要，什么属于备注

我很少在returns标签中添加任何内容，因为这似乎是多余的，因为我通常会在摘要中解释返回的内容。我是否应该简单地将返回的对象类型保留在returns标记中

---

有谁能为这些XML注释提供一种好的、合乎逻辑的或常用的方法，这将有利于团队中的其他程序员，同时又不需要多次显示相同的信息吗？

请记住，这些注释用于帮助其他开发人员理解函数的使用

如果您正在编写一个可能由一个小团队使用的方法，或者如果您正在为一个广泛使用的应用程序构建一个类库或API，那么您对注释的要求就不一样了

我认为除了“让人理解”之外，没有其他规则。

---

如果您真的想更严格一点，可以将MS framework文档作为一个模型来查看。

将类成员的信息分解为正确的部分（摘要、返回、参数、异常），这样其他工具（如对象浏览器、intellisense、类视图等）可以更好地工作

我建议（不是说这是一个“最佳实践”，但它对我很有效）：

-告诉我成员的目的是什么。它的职责是什么？
-给我一个参数的描述。如果您使用，未来的开发人员也将获得该文档的链接。
-描述返回的内容
-告诉开发人员该方法可以引发哪些异常。这使他们有机会在需要时捕获特定异常，而不仅仅是System.Exception。我不经常这样做。

---

我认为，将信息分成小块而不是全部汇总的最大好处是，您可以利用围绕xml文档构建的所有工具。

我使用最多的标记是：

• -带有
  标记的方法/类/成员的用途

• -参数是什么

• -该方法返回什么

• -允许链接引用另一个类/成员（非常适合在构造函数中使用）

• -方法引发的异常的引用

• ..
  -如果您想给出该方法的使用示例

• -描述属性值

• -描述代码段（可与
  一起使用）
  

例子

• 与

  //
  ///初始化类的新实例。
  /// 
  公共表格1（）
  {
  初始化组件（）；
  }

• 与

  //
  ///验证日期。
  /// 
  ///日期。
  ///如果日期有效，则为true；否则就错了。
  公共bool validateDate（字符串日期）
  {
  //做点什么
  }

自动标记生成

您也可以使用免费的VisualStudio插件生成所需的标记，而不是手动插入这些标记

xml标记的使用

---

除了在API（或开发人员帮助文档）中提供信息外，它还允许成员的用户获取重要信息，如方法可以抛出的

异常类型。我引用这个例子是因为知道helper/model类可以抛出什么
exception
类型非常有用。视图/控制器类随后只能捕获这些类型的异常并处理它们。
在我看来，您是正确的，这可能是您最常使用的标签，用于解释方法的确切用途。但是，如果您的方法有好的、有用的名称，那么大多数开发人员都会使用它来对方法的行为做出一些假设。例如，他们假设调用“GetName”可能没有副作用，并返回实例的名称，而不管注释怎么说

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


-指示返回值可能为空。描述返回的
null
与
string.Empty之间的语义差异

-非常适合解释“gotcha”，例如“读卡器必须处于就绪状态，并且光标定位在正确的位置才能开始读取。调用方负责在该方法完成后关闭读卡器。”我通常在对API大惊小怪了半个小时后，在意识到一些不明显的愚蠢细节之前，根据需要添加这些注释。

-好的API应该很容易使用，但有时你会情不自禁。这对于指导如何使用该方法非常有用（尽管您不能保证它将如何使用）。见下面的例子


var token=m_caller.GetAuthToken（）；
var result=m_caller.Call（方法、令牌）；

我相信还有数百个其他的例子我可以想出，但我希望这有助于让你指向正确的方向
 +1。“如果您真的想更严格一点，请将MS framework文档作为一个模型来查看。”-好的建议。
<summary/> - tell me what the member's purpose is. What responsibility does it perform?
<param/> - give me a description of the parameter. If you use <seealso>, future developers will get links to that documentation as well.
<returns/> - describe what is being returned
<exception/> - tell the developer what exceptions can be thrown by the method. This gives them the opportunity to catch specific exceptions if desired, rather than just System.Exception. I don't do this very much.

/// <summary>
/// Initializes a new instance of the <see cref="Form1"/> class.
/// 
public Form1()
{
   InitializeComponent();
}
/// <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
}
<example>
var token = m_caller.GetAuthToken();
var result = m_caller.Call(method, token);
</example>