Чи повинен коментар методу включати як підсумок, так і опис повернення, коли вони часто такі схожі?

Я прихильник правильно задокументованого коду, і добре знаю можливі його недоліки . Це виходить за межі цього питання.

Мені подобається дотримуватися правила додавання коментарів 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взагалі опускаючи документацію.

Повертає істину, коли Список містить елементи, які відповідають умовам, визначеним вказаним предикатом, інакше помилково

Крім того, документація про повернення не відображається в 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, і я величезний прихильник цього. Здається, що в цю категорію потрапляє багато методів одноколірних аксесуарів.

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

вірно, якщо Список містить один або більше елементів, які відповідають умовам, визначеним зазначеним предикатом; в іншому випадку помилково.

стає

вірно, якщо будь-який елемент списку відповідає присудком; інакше помилково.