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

Question

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

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

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

Answer 1

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

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

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

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

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

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

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

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

Answer 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)

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

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

Answer 3

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

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

Answer 4

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

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

(ошибка: недопустимый XML).

Answer 5

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

Answer 6

Я пишу комментарий

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

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

Answer 7

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

Answer 8

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

Компилируйте с /doc, и компилятор будет искать все теги XML висходный код и создайте файл документации XML, затем используйте инструмент, такой как Sandcastle , для генерации полной документации.