Question

当我编写方法并且我想对其进行注释时，我将相同的信息写入摘要标记。

示例：

/// <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)
{
   ...
}

最后，这真的有用吗？提供什么信息以及提供它们的标签？

Answer 1

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

您的文档遗漏的是实际文档。 “字符串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>

如果您使用像我的插件（Atomineer Pro Documentation）这样的工具，那么在类周围复制这些参数详细信息是微不足道的，因此很好地记录您的方法非常耗时。

Answer 2

另一个问题的答案也会回答你的问题：

提供文档真的很有用吗？

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

Answer 3

如果您正在开发库，Xml文档非常有用。可以针对这些xml注释自动生成帮助文件。有关生成帮助文件的详细说明，请参阅this。有关Xml文档标记的信息，请选中MSDN。

Answer 4

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

无论如何，在任何情况下都提供代码文档始终是一个好习惯。

Answer 5

在很多情况下，我发现最好完全删除返回元素。看起来你的例子就是一个很好的例子。值得庆幸的是，VStudio并没有将此标记为带有警告的错误评论。我这样做的原因是因为在80％以上的情况下，我的文档基本上已经描述了返回类型的全部内容，或者，函数的名称是如此明显，以至于它是无用的浪费时间和在我的估计中，能量包括这一点，并且经常导致违反DRY。

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

Customer GetCustomerById(string id)

如果这是一个int id，这个函数可能甚至不需要注释。使用字符串，这不太清楚，可能会使用一些澄清。但无论哪种情况，在返回类型上提供XML注释似乎都是浪费精力。请记住，这是一个主观问题，有些人可能希望为了完成而始终包含返回类型注释，这很好。我很高兴不需要，从VStudio的警告系统开始。

Xml评论中提供了哪些信息？

5 个答案: