Я сторонник надлежащим образом документированного кода, и я хорошо осведомлен о возможных его недостатках . Это выходит за рамки этого вопроса.
Мне нравится следовать правилу добавления комментариев 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
.
- Зачем вам когда-либо нужно документировать
returns
отдельно отsummary
? - Любая информация о том, почему Microsoft приняла этот стандарт?
источник
Мое использование:
<summary>
описывает, что делает метод (чтобы получить<returns>
).<returns>
описывает возвращаемое значение .Ссылки на MSDN:
<summary>
.<returns>
источник
summary
состояния msdn не описывается «что делает метод». Я проголосовал, пока вы не потратите время на обновление своего ответа, чтобы уточнить разницу между тем, что говорится в msdn, и тем, что вы сформулируете. ; ptrue
если предикат был сопоставлен». Если кому-то нужно знать, что составляет совпадение, он может прочитать остальную часть документации.<summary>
и<returns>
сделать это». Как сказал Blrfl, это всего лишь руководство, которое можно или нельзя использовать.Я думаю, что если итоговая часть действительно длинная и описательная, может быть полезно иметь отдельную, краткую возвращаемую часть в конце.
Я обычно пишу только
<summary>
часть в своем собственном коде, формулируя ее так, как вы сказали «Возвращает _ ».Я добавил любые замечания, которые должен знать вызывающий объект, которые не очевидны из имени метода и параметров (и их имен). Хотелось бы надеяться, однако, что имя метода и параметры делают это достаточно очевидным, что комментарий может быть очень кратким.
источник
В последнее время меня мучает тот же философский вопрос, и я до сих пор не уверен, что такое хорошее решение. Но до сих пор это был мой подход ...
источник
returns
вместо этого. Я также заметил, что они всегда используют одну и ту же формулировку, например «true if ...; иначе false. » Для логических возвращаемых значений. Интересно, они также указали соглашение для этого.Резюме должно быть настолько описательным, насколько это может быть полезно; описания параметров и возвращаемого значения должны быть краткими и приятными. Если у вас есть выбор между одним словом и пятью, используйте одно. Давайте подтянем ваш пример:
становится
источник
returns
от Microsoft слишком долго. Если он должен что-то сделать, он просто должен заверить, что true означает, что он соответствует, и false, что это не так.