Что такое Лучшие практики Для Документирования кода C# с XML-комментариями?
Я прохожу некоторый новый код, который я просто написал и добавляющий NDoc sytle комментарии к моим классам и методы. Я надеюсь генерировать довольно хороший документ стиля MSDN для ссылки.
В целом, каковы некоторые хорошие инструкции при записи комментариев для класса и для метода? Что должны сказать комментарии NDoc? Что они не должны говорить?
Я смотрю на то, что комментарии платформы.NET говорят, но который становится старым быстро; если у меня могли бы быть некоторые хорошие правила вести меня, я мог бы закончить свои документы намного быстрее.
8 ответов
В комментариях, используемых для создания документации по API, вы должны:
Объяснять, что делает метод или свойство, почему они вообще существуют, и объяснять любые концепции предметной области, которые не очевидны для среднего потребителя вашего кода.
Перечислите все предварительные условия для ваших параметров (не может быть пустым, должно быть в определенном диапазоне и т. Д.).
Перечислите любые постусловия, которые могут повлиять на то, как вызывающие объекты обрабатывают возвращаемые значения.
Перечислите любые исключения, которые метод может вызвать (и при каких обстоятельствах).
Если существуют похожие методы, объясните различия между ними.
Привлекайте внимание ко всему неожиданному (например, изменению глобального состояния).
Перечислите побочные эффекты, если они есть.
StyleCop предоставляет подсказки для стиля комментирования кода и . Предложения, которые он дает, соответствуют стилю документации MSDN.
Что касается содержания комментария, он должен давать пользователю вашего кода достаточно информации о том, какого поведения ожидать. Он также должен ответить на потенциальные вопросы, которые могут возникнуть у пользователя. Поэтому попробуйте использовать свой код как человек, который ничего не знает о коде, или, что еще лучше, попросите об этом кого-то другого.
Не забывайте, что такое действительный XML. Например:
/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>
(Ошибка: недопустимый XML).
Одна вещь о комментариях - это их обновление. Слишком много людей изменяют функцию, а затем не меняют комментарий, чтобы отразить изменения.
Как указано на странице MSDN, вы используете комментарии к документации XML для автоматической генерации документации, так что это имеет смысл, если вы пишете API и не хотите дважды работать над кодом и документацией, с дополнительным преимуществом синхронизации - каждый раз, когда вы изменяете код, вы изменяете соответствующие комментарии и заново генерируете документацию.
Компилируйте с /doc, и компилятор будет искать все XML-теги в исходном коде и создавать XML-файл документации, затем используйте инструмент, такой как Sandcastle, для генерации полной документации.
Я пишу комментарий
Я пишу комментарий
Для свойств ваш комментарий должен указывать, является ли свойство доступным только для чтения, только для записи или для чтения и записи. Если вы посмотрите на всю официальную документацию MS, комментарии к документации свойств всегда начинаются с «Gets ...», «Gets or sets ...» и (очень редко, обычно избегайте только записи свойств) «Sets ...»
Если в итоге вы получите комментарии, которые не добавляют никакой ценности, они просто расточительны.
Например
/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)
... вы не добавили абсолютно никакой ценности, а просто добавили дополнительный код для поддержки.
Слишком часто код завален этими лишними комментариями.