Question

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

我从未在评论中添加任何内容，因为我将方法的描述放在摘要标记中。 摘要中包含哪些内容以及备注中包含哪些内容？

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

任何人都可以建议这些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
}

自动标记生成

您可以使用Ghost Doc之类的免费视觉工作室插件来生成所需的标记，而不是尝试手动插入这些标记。

使用xml标签

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

Answer 2

在我看来，你是对的＆lt; summary＆gt;可能是您最常使用的标记，用于解释您的方法究竟要做什么。但是，如果您的方法具有良好，有用的名称，那么期望大多数开发人员将使用它来对该方法的行为方式做出一些假设。例如，他们假设调用“GetName”可能没有副作用，并返回实例的名称，无论评论说什么。

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

<returns> - 表示返回值可能为null。描述返回null与string.Empty
<remarks> - 非常适合解释“陷阱”，例如“读者必须处于就绪状态，光标位于正确的位置才能开始阅读。调用者负责在此方法完成后关闭阅读器。”我经常在使用API半小时后根据需要添加这些注释，然后才意识到一些不明显的愚蠢细节。
<example> - 好的API应该易于使用，但有时你无法帮助它。这非常适合提供有关如何使用预期方法的指导（尽管您不能保证将如何使用）。见下面的例子。

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

我确信我还有其他几百个可以想象的例子，但我希望这有助于让你指出正确的方向！

Answer 3

请注意，此注释用于帮助其他开发人员了解该功能的使用。

如果您正在编写一个可能由小团队使用的方法，或者您正在为广泛使用的应用程序构建类库或API，则不具有相同的注释要求。

我认为除了“保持可理解性”之外别无其他规则。如果您真的想要更严格一些，请查看MS框架文档作为模型。

Answer 4

将有关您的类成员的信息分解为正确的部分（summary，returns，param，exception）允许其他工具（如对象浏览器，智能感知，类视图等）更好地工作。

我建议（不是说这是“最佳做法”，但它适用于我）：

<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.

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

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

4 个答案: