Каковы наилучшие практики для документирования кода на С# с комментариями XML?

Я просматриваю новый код, который я только что написал, и добавляю комментарии NDoc sytle к своим классам и методам. Я надеюсь создать хороший документ в стиле MSDN для справки.

В целом, какие хорошие рекомендации при написании комментариев для класса и метода? Что должны делать комментарии NDoc? Что они не должны сказать?

Я нахожу, что смотрю, что говорят комментарии .NET Framework, но быстро стареет; если бы у меня были хорошие правила для руководства, я мог бы закончить свои документы намного быстрее.

Ответы

Ответ 1

В комментариях, используемых для создания документации API, вам необходимо:

  • Объясните, что делает метод или свойство, почему он вообще существует, и объясняйте любые концепции домена, которые не являются очевидными для среднего потребителя вашего кода.

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

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

  • Перечислите любые исключения, которые метод может использовать (и при каких обстоятельствах).

  • Если подобные методы существуют, объясните различия между ними.

  • Обратите внимание на что-нибудь неожиданное (например, изменение глобального состояния).

  • Перечислите любые побочные эффекты, если они есть.

Ответ 2

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

Например

/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)

... вы добавили абсолютно никакой ценности и просто добавили больше кода для поддержки.

Слишком часто код завален этими лишними комментариями.

Ответ 3

StyleCop содержит подсказки для стиля кода и комментариев. Предложения, которые он дает, соответствуют стилю документации MSDN.

Что касается содержимого комментария, он должен предоставить пользователю вашего кода достаточно информации о том, какое поведение ожидать. Он также должен отвечать на возможные вопросы, которые могут возникнуть у пользователя. Поэтому попробуйте использовать свой код как кто-то, кто ничего не знает о коде, или даже лучше, попросите кого-нибудь сделать это.

Ответ 4

Для свойств ваш комментарий должен указывать, является ли свойство только для чтения, только для записи или чтения записи. Если вы посмотрите на всю официальную документацию MS, комментарии к документам свойств всегда начинаются с "Gets...", "Gets or sets..." и (очень редко избегайте обычно только свойств записи) "Sets..."

Ответ 5

Не забывайте, что такое действительный XML. Например:

/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>

(Ошибка: неверный XML).

Ответ 6

Я пишу <summary> комментарий, чтобы включить информацию, которую я хотел бы знать, был ли я тем, кто вызывал эту функцию (или создавал экземпляр этого класса).

Я пишу < замечания > комментарий, чтобы включить информацию, которую я хотел бы знать, если мне было поручено отлаживать или улучшать эту функцию или класс. Примечание: это не заменяет необходимость в хороших встроенных комментариях. Но иногда общий обзор внутренней работы функции/класса очень полезен.

Ответ 7

Как указано на странице Sandcastle для создания полных документов.

Ответ 8

Одна вещь о комментариях - ОБНОВЛЕНИЕ. Слишком много людей меняют функцию, а затем не изменяют комментарий, чтобы отразить изменения.