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

StackOverflow https://stackoverflow.com/questions/3143324

  •  01-10-2019
  •  | 
  •  

Вопрос

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

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

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

Это было полезно?

Решение

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

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

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

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

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

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

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

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

Другие советы

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

Например

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

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

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

Стилекоп Обеспечивает подсказки для кода а также Комментирующий стиль. Предложения, которое он дает, соответствует стилю документации MSDN.

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

Для недвижимости ваш комментарий должен указывать, только ли только чтение имущество, запись только записать или читайте запись. Если вы посмотрите на всю официальную документацию MS, свойство DOC Comments Всегда начинается с «Получает ...», «Получает или устанавливает ...» и (очень редко, избегайте писать только свойства, обычно) «Наборы ...»

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

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

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

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

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

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

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

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

Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top