Должен ли комментарий метода включать как краткое изложение, так и возвращаемое описание, когда они часто бывают похожими?

Я сторонник надлежащим образом документированного кода, и я хорошо осведомлен о возможных его недостатках . Это выходит за рамки этого вопроса.

Мне нравится следовать правилу добавления комментариев XML для каждого публичного участника, учитывая, насколько мне нравится IntelliSense в Visual Studio.

Однако существует одна форма избыточности, которая беспокоит даже такого чрезмерного комментатора, как я. В качестве примера возьмем 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документацию вообще.

Возвращает true, если List содержит элементы, которые соответствуют условиям, определенным указанным предикатом, в противном случае - 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/>и вывести ожидаемое возвращаемое значение из сводки. Но доводя один и тот же аргумент до крайности, в этом случае совсем не нужно документировать свой метод : имя метода, помещенное внутрь List<T>, Predicate<T> matchкак единственный аргумент, само по себе совершенно очевидно.

Помните, что исходный код пишется один раз, но читается много раз . Если вы можете уменьшить акцизы для дальнейших читателей вашего кода, потратив десять секунд на написание дополнительного предложения в документации XML, сделайте это.

Мое использование:
<summary>описывает, что делает метод (чтобы получить <returns>).
<returns>описывает возвращаемое значение .

Ссылки на MSDN: <summary>.<returns>

Зачем вам когда-либо нужно документировать возвраты отдельно от резюме?

Я думаю, что если итоговая часть действительно длинная и описательная, может быть полезно иметь отдельную, краткую возвращаемую часть в конце.

Я обычно пишу только <summary>часть в своем собственном коде, формулируя ее так, как вы сказали «Возвращает _ ».

Я добавил любые замечания, которые должен знать вызывающий объект, которые не очевидны из имени метода и параметров (и их имен). Хотелось бы надеяться, однако, что имя метода и параметры делают это достаточно очевидным, что комментарий может быть очень кратким.

В последнее время меня мучает тот же философский вопрос, и я до сих пор не уверен, что такое хорошее решение. Но до сих пор это был мой подход ...

• Документация по методу описывает только то, что должны знать внешние абоненты. Здесь не говорится о том, как эта работа выполняется внутри, но упоминается а) почему вызывающий объект захочет вызвать этот метод, б) каковы ожидаемые результаты вызова метода. Если есть необходимость документировать, как работает метод, я помещаю это в сам код.
• Если метод имеет достаточную сложность, то общее описание и отдельный раздел [return] представляются оправданными. Вы не хотите, чтобы читатель прочитал полное описание и попытался сделать вывод, как интерпретировать возвращаемое значение.
• Если метод настолько прост, что лучший способ описать, что он делает, это сказать что-то вроде «Этот метод возвращает адрес человека», тогда я пропускаю раздел [return], так как добавление может показаться противоречащим принципу DRY, и я огромный сторонник этого. Многие однострочные методы доступа, похоже, попадают в эту категорию.

Резюме должно быть настолько описательным, насколько это может быть полезно; описания параметров и возвращаемого значения должны быть краткими и приятными. Если у вас есть выбор между одним словом и пятью, используйте одно. Давайте подтянем ваш пример:

Значение true, если список содержит один или несколько элементов, соответствующих условиям, заданным указанным предикатом; иначе ложно.

становится

Значение true, если какой-либо элемент списка соответствует предикату; иначе ложно.