我应该如何编写XML注释以避免在摘要和返回标记之间重复？

Question

当方法的目的是计算一个值并将其返回时,我发现自己将其记录如下:

/// <summary>
/// Calculates the widget count.
/// </summary>
/// <param name="control">The control to calculate the widget count of.</param>
/// <returns>The widget count.</returns>

这里的returns标签没有提供任何新的信息:它只是重复了什么summary.(唯一的例外是返回的方法bool,在那里可以很容易地解释一下什么是true和false返回值的意思.)

我错过了什么吗？是否有标准的XML文档块措辞方法,以避免summary和returns标签之间的重复？

Answer 1

有时文档往往会重复,特别是对于属性(对于外部调用者,他们应该看起来和感觉就像简单的值,因此很难看到提供'summary'和'value'条目的任何要点).

因此,我尝试区分摘要和param/returns/value等,以减少重复性.摘要简要描述了该方法的作用(计算小部件计数),而param/returns/value给出了输入/输出的详细信息(没有别的).在许多情况下,您会看到条目之间存在更明显的差异 - 阅读您的示例,我立即对文档没有回答的API有疑问,所以我希望看到更像这些替代方案之一:

/// <summary>Recursively calculates the widget count for a given control.</summary> 
///
/// <param name="control">The root control of the subtree to process, or null.</param> 
///
/// <returns>
/// The number of widgets that are contained within 'control' and its
/// entire subtree of descendant controls (or 0 if control is null).
/// </returns>

要么...

/// <summary>Calculates the widget count for a given control.</summary> 
///
/// <param name="control">The control to process. May be null.</param> 
///
/// <returns>
/// The number of widgets that are direct children of 'control', or
/// -1 if it is null/not a registered control.
/// </returns>

甚至 ...

/// <summary>
/// Calculates the widget 'count' for a given control using the
/// Wicker-Bartland meanest minimum average algorithm.
/// </summary>
///
/// <param name="control">
/// The Wicker-Bartland control-input-value, in the range 1.0 .. 42.6
/// </param> 
///
/// <returns>
/// The widget count, in the range -2PI .. +2PI, or Double.NaN if the
/// input control value is out of range.
/// </returns>

与@Bertie似乎建议的不同,我总是试图减少冗长并增加信息内容 - 正如您所知道的方法所做的那样,您可能不需要参数描述中那么多细节来描述它的用途,因为它是通常非常明显/直观 - 但您通常可以添加更多有关合法值或参数使用方式的详细信息,以帮助读者了解如何最好地使用它.类似地,关于我将获得什么样的返回值的详细信息(例如,我是否可以返回零,负值,空值等)

将此文档视为定义代码合同 - 更明确地说明合同,它变得越不明确,另一个程序员就越容易理解他们如何(而且不能)使用您的方法而不必阅读源代码.或者确定您的方法的行为是否符合预期或错误.或者知道他们可以在不破坏任何现有调用代码的情况下改变方法的行为.

当然,在某些情况下,方法确实非常简单明了,您可以使用AtomineerUtils对其进行注释并继续前进,从而为更重要的工作节省时间.编程通常需要在实际(完成工作和发运产品)和满足理论理想(DRY等)之间取得平衡.