<分区>
当方法的目的是计算一个值并返回它时，我发现自己将其记录如下:
/// <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 中的内容。 (异常(exception)是返回 bool 的方法，其中很容易解释 true 和 false 返回值的含义。)
我错过了什么吗？是否有一种标准的 XML 文档 block 措辞方式来避免 summary 和 returns 标记之间的重复？
最佳答案
有时文档确实倾向于 self 重复，尤其是对于属性(对于外部调用者来说，它们看起来和感觉起来应该就像简单的值一样，因此很难看出同时提供“摘要”和“值”条目有什么意义)。
所以我尝试在摘要和参数/返回/值等之间划清界限，以减少重复性。摘要简要描述了该方法的作用(计算小部件计数)，而参数/返回/值给出了输入/输出的详细信息(仅此而已)。在许多情况下，您会发现条目之间存在更明显的差异 - 阅读您的示例，我立即对文档没有回答的 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 等)之间取得平衡。
关于c# - 我应该如何编写 XML 注释以避免在摘要和返回标记之间重复自己？，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/9016732/