16

当方法的目的是计算一个值并返回它时，我发现自己记录它如下：

/// <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 文档块措辞方式来避免summaryandreturns标记之间的重复？

4

2 回答 2

11

有时文档确实会重复，尤其是属性（对于外部调用者来说，它们应该看起来和感觉就像简单的值，所以很难看出同时提供“摘要”和“值”条目有什么意义）。

因此，我尝试区分摘要和参数/返回/值等，以减少重复性。摘要简要描述了该方法的作用（计算小部件计数），而参数/返回/值给出了输入/输出的详细信息（仅此而已）。在许多情况下，您会看到条目之间存在更显着的差异 - 阅读您的示例，我立即对文档没有回答的 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 等）之间取得平衡。

于 2012-01-27T23:51:24.690 回答
4

您也可以尝试使摘要更详细地说明该方法的工作原理，而无需详细说明。例如

/// <summary> 
/// Using the <paramref name="control"/> parameter, calculate the total number of widgets it contains.
/// </summary> 
/// <param name="control">The control to calculate the widget count of.</param> 
/// <returns>The total widgets contained in <paramref name="control"/>.returns>

在某些情况下，返回值可能需要更多解释——玩弄它，看看它是什么样子。基本上想象有人把这个文档作为 API 的一部分交给你，你必须在没有看到代码的情况下使用它。

于 2012-01-26T10:40:53.477 回答