Каковы лучшие практики для документирования кода C# с комментариями XML?
Я просматриваю новый код, который только что написал, и добавляю комментарии NDoc sytle к своим классам и методам. Я надеюсь создать довольно хороший документ в стиле MSDN для справки.
В целом, каковы хорошие рекомендации при написании комментариев для класса и метода? Что должны сказать комментарии NDoc? Что они не должны сказать?
Я вижу, что говорят комментарии.NET Framework, но это быстро устареет; если бы у меня были хорошие правила, которыми я мог бы руководствоваться, я мог бы закончить свои документы намного быстрее.
8 ответов
В комментариях, используемых для создания документации 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)
... вы добавили абсолютно никакой ценности и просто добавили больше кода для поддержки.
Слишком часто код завален этими лишними комментариями.
StyleCop предоставляет подсказки для кода и стиля комментирования. Предложения, которые он дает, соответствуют стилю документации MSDN.
Что касается содержания комментария, он должен дать пользователю вашего кода достаточно информации о том, какое поведение ожидать. Он также должен отвечать на потенциальные вопросы, которые могут возникнуть у пользователя. Поэтому старайтесь использовать свой код как кого-то, кто ничего не знает о коде, или даже лучше, попросите кого-то сделать это.
Для свойств ваш комментарий должен указывать, является ли свойство только для чтения, только для записи или для чтения и записи. Если вы посмотрите на всю официальную документацию MS, комментарии к документации по свойствам всегда начинаются с "Gets ...", "Gets or sets..." и (очень редко, обычно избегают только свойства записи) "Sets ..."
Не забывайте, что такое правильный XML. Например:
/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>
(Ошибка: неверный XML).
Я пишу комментарий
Я пишу комментарий
Как указано на странице MSDN, вы используете комментарии к документации XML для автоматического создания документации, поэтому имеет смысл, если вы пишете API и не хотите дважды работать как с кодом, так и с документацией, с дополнительным преимуществом сохранения их в синхронизировать - каждый раз, когда вы изменяете код, вы изменяете соответствующие комментарии и регенерируете документы.
Компилировать с /doc и компилятор будет искать все теги XML в исходном коде и создавать файл документации XML, а затем использовать инструмент, такой как Sandcastle, для генерации полной документации.
Одна вещь о комментариях - ОБНОВЛЕНИЕ их. Слишком много людей изменяют функцию, затем не меняют комментарий, чтобы отразить это изменение.