我最近一直在我的程序顶部使用方法摘要 XML 注释，我想知道是否有任何与此相关的合乎逻辑或良好做法。
我从不在备注中添加任何内容，因为我将方法的描述放在了摘要标记中。 什么属于摘要，什么属于备注？
我很少在返回标签中放任何东西，因为这似乎是多余的，因为我通常会在摘要中解释返回的内容。 我应该只保留返回标签中返回的对象类型吗？
任何人都可以就这些 XML cmets 的一种好的、合乎逻辑的或常用的方法提出建议，该方法对团队中的其他程序员有益，同时不需要多次显示相同的信息？
【问题讨论】：
我用得最多的标签是：
<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 类型。我引用这个例子是因为知道帮助器/模型类可以抛出哪些exception 类型非常有帮助。然后视图/控制器类可以只捕获这些类型的异常并处理它们。
【讨论】：
在我看来，你是正确的，
考虑到这一点，我倾向于将我的 cmets 重点放在我知道的任何“陷阱”上，而不是写下关于该方法应该做什么的段落，知道如果有人使用我的代码并且它不起作用按照他们认为应该的方式，他们要做的第一件事就是查看文档，希望得到一些指导。下面是我如何使用各种标签的几个示例。
<returns> - 表示返回值可能为空。描述返回 null 与 string.Empty 之间的语义差异<remarks> - 非常适合解释“陷阱”，例如“阅读器必须处于就绪状态，并且光标定位在正确的位置才能开始阅读。调用者负责在此方法完成后关闭阅读器。”我通常会在使用 API 半小时后根据需要添加这些 cmets，然后才意识到一些不明显的愚蠢细节。<example> - 好的 API 应该易于使用，但有时您无能为力。这对于指导如何打算使用该方法非常有用（尽管您不能保证将使用该方法）。请参见下面的示例。<example>
var token = m_caller.GetAuthToken();
var result = m_caller.Call(method, token);
</example>
我敢肯定，我还可以想象出数百个其他示例，但我希望这能帮助您指明正确的方向！
【讨论】：
请记住，此 cmets 用于帮助其他开发人员了解该函数的使用。
如果您正在编写可能被小团队使用的方法，或者如果您正在为广泛使用的应用程序构建类库或 API，则没有相同的注释要求。
我认为除了“保持可理解”之外没有其他规则。 如果你真的想更严谨一点，可以看看 MS 框架文档作为模型。
【讨论】：
将有关您的班级成员的信息分解为正确的部分（摘要、返回、参数、异常）可以让其他工具（如对象浏览器、智能感知、班级视图等）更好地工作。
我建议（不是说这是“最佳实践”，但它对我有用）：
<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 文档构建的所有工具。
【讨论】：