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

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

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

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

36
c# code-documentation ndoc

8 ответов

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

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

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

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

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

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

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

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

51

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

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

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

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

16

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

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

6

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

5

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

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

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

5

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

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

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

2

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

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

0

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

0