在Xml注释中提供哪些信息

本文关键字：信息 Xml 注释 | 更新日期: 2023-09-27 18:29:26

当我编写一个方法并对其进行注释时，我会将相同的信息写入summary标记。

示例：

/// <summary>
/// Get a <typeparamref name="Customer">customer</typeparamref> by its ID 
/// </summary>
/// <param name="id">customer id</param>
/// <returns>a <typeparamref name="Customer">customer</typeparamref></returns>
private Customer GetCustomerById(string id)
{
   ...
}

最后，这真的有用吗？提供哪些信息，在哪个标签中提供？

在Xml注释中提供哪些信息

考虑DRY（不要重复）。param条目描述参数，return条目描述返回的内容。摘要应该概述该方法的作用，而不是重复其他条目中的信息。

您的文档缺少的是实际文档。"字符串id"是一个包含id的字符串，它是自记录的。但是我该如何调用这个方法：什么包含有效的用户id？如果我传入一个null或空字符串，会发生什么？等

下面是一个假设的例子，其中包括关于事物的用途以及如何使用该方法的文档：

/// <summary> Gets information on a customer </summary>
///
/// <param name='id'> A customer identifier in the form of a GUID string.
/// e.g. "{D8C447DD-0E7F-4C8B-A3E5-2C6E160D297B}".
/// Braces around the GUID are optional.
/// This parameter must be a valid Guid. </param>
///
/// <returns> A Customer record describing the given customer, or
/// null if the Customer is not found</returns>

如果你使用像我的addin（Atomineer Pro Documentation）这样的工具，那么围绕类复制这些参数细节是微不足道的，所以很好地记录你的方法不需要花费时间。

另一个问题的答案也会在您的问题上得到答案：

提供文档真的有用吗？

提供你想要的任何东西，你认为需要的和有用的东西。此信息将作为IntelliSense工具提示显示给Visual Studio中的代码使用者，就像您在.NET类和成员中看到的那样。

Xml文档在开发库时非常有用。可以根据这些xml注释自动生成帮助文件。有关生成帮助文件的详细讨论，请参见此。有关Xml文档标记的信息，请查看MSDN。

有时方法或属性名称是不言自明的，但情况并非总是如此。事件与您的例子。您应该提供信息，如果提供的ID不存在会发生什么。你的方法会抛出一个异常吗（如果是，那么会是什么异常），或者可能只是返回null，或者某种普通的Customer.Empty值？有时您甚至可以提供一些代码示例。

无论哪种方式，在任何情况下提供代码文档都是一种很好的做法。

在很多情况下，我发现最好完全去掉return元素。你的例子似乎就是一个很好的例子。值得庆幸的是，VStudio并没有将此标记为带有警告的差评。我这样做的原因是，在80%以上的情况下，我的文档基本上已经描述了返回类型的全部内容，或者，函数的名称太明显了，在我看来，包括它是对时间和精力的无用浪费，而且它经常会导致违反DRY。

你的例子就是一个很好的例子。

Customer GetCustomerById(string id)

如果这是一个int id，那么这个函数可能甚至不需要注释。对于字符串，这不太清楚，可能需要一些澄清。但在任何一种情况下，为返回类型提供XML注释似乎都是浪费精力。请记住，这是一个主观的问题，有些人可能喜欢为了完成而总是包含返回类型的评论，这很好。我很高兴它不是必需的，但从VStudio的警告系统开始。

相关文章：