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

10

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

Мне нравится следовать правилу добавления комментариев 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 приняла этот стандарт?
Стивен Джеурис
источник

Ответы:

3

Вы можете вывести одно из другого, но эти два раздела остаются отдельными, потому что это помогает сосредоточиться на том, который интересует человека при просмотре / использовании кода .

Принимая ваш пример, я бы лучше написал:

/// <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, сделайте это.

Арсений Мурзенко
источник
1
Вы вызываете метод и не хотите знать, что он делает !?
JK.
1
@jk: Он подразумевает, что он уже сделал это заранее. Только когда это не удается, он хочет «сосредоточиться» на возвращаемом значении. +1 за последний абзац, по сути, я тоже так себя чувствую. Даже если в документации указан очевидный факт, как в моем примере, это успокаивает читателя в его ожиданиях. Когда комментарии обрабатываются должным образом, он говорит: «этот метод продуман правильно и не делает ничего, кроме того, что упомянуто здесь», как в документации msdn.
Стивен Джеурис
2

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

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

Джейк Бергер
источник
Спасибо за ссылку. Но нигде в документации summaryсостояния msdn не описывается «что делает метод». Я проголосовал, пока вы не потратите время на обновление своего ответа, чтобы уточнить разницу между тем, что говорится в msdn, и тем, что вы сформулируете. ; p
Стивен Джеурис
2
Независимо от того, говорит ли MSDN об этом или нет, на самом деле это хорошее руководство. В вашем примере вам не нужно повторять всю сводку, вы можете просто сказать «возвращается, trueесли предикат был сопоставлен». Если кому-то нужно знать, что составляет совпадение, он может прочитать остальную часть документации.
Blrfl
@Blrfl: я не говорю, что руководство неверно. Я говорю, что неправильно ссылаться на источник, подразумевая, что там что-то написано, когда это не так. Отсюда и голосование вниз. Я бы очень хотел, чтобы этот ответ был отредактирован.
Стивен Джеурис
@StevenJeuris: ссылки на документацию MSDN были просто дополнительной информацией. MSDN НЕ говорит: «Если у вас есть <summary>и <returns>сделать это». Как сказал Blrfl, это всего лишь руководство, которое можно или нельзя использовать.
Джейк Бергер
1
@StevenJeuris: Хотя из-за того, как это было написано, я мог видеть, как кто-то может сделать вывод, что он пришел из MSDN.
Джейк Бергер
1

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

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

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

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

Филипп
источник
1

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

  • Документация по методу описывает только то, что должны знать внешние абоненты. Здесь не говорится о том, как эта работа выполняется внутри, но упоминается а) почему вызывающий объект захочет вызвать этот метод, б) каковы ожидаемые результаты вызова метода. Если есть необходимость документировать, как работает метод, я помещаю это в сам код.
  • Если метод имеет достаточную сложность, то общее описание и отдельный раздел [return] представляются оправданными. Вы не хотите, чтобы читатель прочитал полное описание и попытался сделать вывод, как интерпретировать возвращаемое значение.
  • Если метод настолько прост, что лучший способ описать, что он делает, это сказать что-то вроде «Этот метод возвращает адрес человека», тогда я пропускаю раздел [return], так как добавление может показаться противоречащим принципу DRY, и я огромный сторонник этого. Многие однострочные методы доступа, похоже, попадают в эту категорию.
DXM
источник
Да, я могу соединиться с упомянутыми пунктами, и более или менее следовать им. Проблема в том, что это довольно субъективное соглашение, которое может быть причиной, по которой Microsoft просто предпочитает всегда добавлять returnsвместо этого. Я также заметил, что они всегда используют одну и ту же формулировку, например «true if ...; иначе false. » Для логических возвращаемых значений. Интересно, они также указали соглашение для этого.
Стивен Джеурис
0

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

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

становится

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

Калеб
источник
На самом деле, его написание просто заставило меня осознать преимущество стандартного способа Microsoft начать с «Определяет ...» . Я чувствую, что он более читабелен, так как сначала объясняет, что он делает, а потом рассказывает, каков его результат. Это на шаг меньше косвенности. Я согласен, что returnsот Microsoft слишком долго. Если он должен что-то сделать, он просто должен заверить, что true означает, что он соответствует, и false, что это не так.
Стивен Джеурис