当方法注释经常如此相似时，是否应该同时包含摘要和返回说明？

我是正确编写代码的支持者，并且我很清楚其可能存在的弊端。这超出了这个问题的范围。

考虑到我在Visual Studio中非常喜欢IntelliSense，我喜欢遵循为每个公共成员添加XML注释的规则。

但是，存在一种形式的冗余，即使像我这样的过多评论者也会对此感到困扰。以List.Exists（）为例。

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summary并且returns基本上是说同样的事情。我通常最终会从一个returns角度写更多的摘要，而returns完全放弃了文档。

当List包含与指定谓词定义的条件匹配的元素时，返回true；否则返回false。

此外，退货文档未显示在IntelliSense中，因此我宁愿在中写入任何直接相关的信息summary。

1. 为什么您需要returns单独记录summary？
2. 关于Microsoft为什么采用此标准的任何信息？

您可以相互推论，但是这两个部分是分开的，因为这有助于将重点放在在查看/使用代码时使人感兴趣的地方。

以您的示例为例，我宁愿写：

/// <summary>
/// Determines whether the List<T> contains elements that match the conditions
/// defined by the specified predicate.
/// </summary>
/// <returns>
/// A value indicating whether at least one element matched the predicate.
/// </returns>
public bool Exists(Predicate<T> match)
{
    ...
}

• 如果我正在查看此代码，并且想知道该方法的作用，请阅读摘要，这就是我所关心的全部。

• 现在，让我们想象一下我正在使用您的方法，给定输入，我收到的返回值很奇怪。现在，我真的不想知道该方法的作用，但是我想进一步了解返回值。在这里，本<returns/>节对您有帮助，我不需要阅读摘要。

同样，在此示例中，您可以从推断出摘要<returns/>，并从摘要推断出预期的返回值。但是，将相同的参数放到极致，在这种情况下根本不需要记录您的方法：方法名称（放在inside中List<T>，Predicate<T> match作为唯一参数）本身非常明确。

请记住，源代码只编写了一次，但阅读了很多次。如果您可以减少代码读者的负担，而又花十秒钟在XML文档中写一个额外的句子，那就去做。

我的用法：
<summary>描述该方法的作用（获取<returns>）。
<returns>描述返回值。

链接到MSDN ：<summary>。<returns>

为什么您需要将退货单与汇总单分开记录？

我认为，如果摘要部分确实很长且具有描述性，那么在结尾处使用单独的简短返回部分可能会很有用。

我通常只<summary>在自己的代码中编写该部分，并用您说“ Returns _ ”的方式写出来。

我在讲话中提到，调用者应该知道，从方法名称和参数（及其名称）来看并不明显。但是，希望方法名称和参数足够明显，以使注释可以非常简短。

最近，我一直被同一个哲学问题困扰，但我仍然不确定什么是好的解决方案。但是到目前为止，这是我的方法...

• 方法文档仅描述外部呼叫者需要知道的内容。它没有谈论如何在内部完成这项工作，而是提到了a）调用方为什么要调用此方法，b）调用该方法的预期结果是什么。如果需要记录该方法的工作方式，我会将其放入代码主体本身。
• 如果一种方法具有足够的复杂性，那么一般的描述和单独的[returns]部分似乎是合理的。您不希望读者阅读整个描述并尝试推断如何解释返回值。
• 如果该方法是如此简单，以至于描述该方法的最佳方法是说“此方法返回某人的住址”之类的内容，那么我跳过[returns]部分，因为添加似乎违反了DRY原理，一个巨大的拥护者。许多单线访问器方法似乎属于此类。

摘要应尽可能具有描述性；参数和返回值的描述应该简短而优美。如果您在一个单词和五个单词之间进行选择，请使用一个。让我们收紧您的示例：

如果List包含一个或多个与指定谓词定义的条件匹配的元素，则为true；否则为true。否则为假。

变成

如果List的任何元素与谓词匹配，则为true；否则为true。否则为假。