Как написать XML-комментарии, чтобы избежать повторения между тегами summary и returns? [закрытый]

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

/// <summary>
/// Calculates the widget count.
/// </summary>
/// <param name="control">The control to calculate the widget count of.</param>
/// <returns>The widget count.</returns>
на returns тег не дает никакой новой информации: он просто повторяет то, что в summary. (Исключение составляют методы, возвращающие bool, где легко объяснить, что такое true и false возвращаемые значения mean.)

Я что-то пропустила? Есть ли стандартный способ формулировки блоков документации XML, чтобы избежать повторение между summary и returns теги?

15
c# comments documentation xml-documentation

2 ответов

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

поэтому я пытаюсь провести различие между summary и param / returns / value и т. д., что уменьшает повторяемость. В сводке кратко описывается, что делает метод (вычисляет количество виджетов), в то время как param / returns / value дает подробную информацию входы / выходы (и ничего больше). Во многих случаях вы видите более заметную разницу между записями-читая ваш пример, у меня сразу возникают вопросы об API, на которые документация не отвечает, поэтому я надеюсь увидеть что-то более похожее на одну из этих альтернатив:

/// <summary>Recursively calculates the widget count for a given control.</summary> 
///
/// <param name="control">The root control of the subtree to process, or null.</param> 
///
/// <returns>
/// The number of widgets that are contained within 'control' and its
/// entire subtree of descendant controls (or 0 if control is null).
/// </returns>

или...

/// <summary>Calculates the widget count for a given control.</summary> 
///
/// <param name="control">The control to process. May be null.</param> 
///
/// <returns>
/// The number of widgets that are direct children of 'control', or
/// -1 if it is null/not a registered control.
/// </returns>

или даже ...

/// <summary>
/// Calculates the widget 'count' for a given control using the
/// Wicker-Bartland meanest minimum average algorithm.
/// </summary>
///
/// <param name="control">
/// The Wicker-Bartland control-input-value, in the range 1.0 .. 42.6
/// </param> 
///
/// <returns>
/// The widget count, in the range -2PI .. +2PI, or Double.NaN if the
/// input control value is out of range.
/// </returns>

В отличие от того, что @Bertie, кажется, предлагает, я всегда стараюсь уменьшить многословие и увеличить the информационный контент - поскольку вы знаете, что делает метод, вам может не понадобиться так много деталей в описании параметра, чтобы описать, для чего он предназначен, поскольку это часто довольно очевидно/интуитивно, но вы часто сможете добавить более подробную информацию о том, какие значения являются законными или как используется параметр, чтобы помочь читателю понять, как лучше его использовать. Аналогично для деталей о том, какое возвращаемое значение я получу (например, могу ли я получить ноль, отрицательные значения, нули, и т. д.)

подумайте об этой документации как об определении контракта кода - чем более явно вы указываете контракт, тем менее двусмысленным он становится, и тем легче другой программист сможет понять, как они могут (и не могут) использовать ваш метод без необходимости читать исходный код. Или определите, является ли поведение вашего метода намеренным или ошибкой. Или знать, насколько они могут изменить поведение вашего метода, не нарушая ни одного из существующих вызовов код.

конечно, в некоторых случаях метод очень прост и достаточно очевиден, что вы можете просто комментировать с AtomineerUtils и двигаться дальше, экономя время для более важной работы. Часто программирование должно быть балансом между практичностью (выполнение работы и отгрузка продукта) и соответствием теоретическим идеалам (сухой и т. д.).

10

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

/// <summary> 
/// Using the <paramref name="control"/> parameter, calculate the total number of widgets it contains.
/// </summary> 
/// <param name="control">The control to calculate the widget count of.</param> 
/// <returns>The total widgets contained in <paramref name="control"/>.returns>

в некоторых случаях возвращаемое значение может потребовать немного больше объяснений-поиграйте с ним и посмотрите, как он выглядит. В основном представьте, что кто-то передал вам эту документацию как часть API, которую вы должны использовать, даже не видя кода.

4