XML-комментарии для программирования С#

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

Это всего лишь общий вопрос о комментировании XML в С#. Я никогда не был настолько большим, чтобы комментировать мои программы, я всегда был более многословным переменной/свойство/метод namer и позволял коду говорить сам за себя. Я пишу комментарии, если я кодирую что-то довольно запутанное, но по большей части я не пишу много комментариев.

Я читал о комментариях XML в .NET, Sandcastle и построителе файлов справки на codeplex, и это привело меня к тому, что я захотел задокументировать свой код и создать полезную документацию для тех, кто должен в мой код, когда меня больше нет.

Мой вопрос касается стандартов и конвенций. Есть ли руководство по "хорошему" комментированию XML? Должны ли вы прокомментировать КАЖДУНУЮ переменную и свойство? КАЖДЫЙ метод? Я просто в основном ищут советы о том, как писать хорошие комментарии, которые будут скомпилированы sandcastle в хорошую документацию, поэтому другие программисты не проклинают мое имя, когда им приходится работать с моим кодом.

Заранее благодарим за ваши советы и предложения, Скотт Веркуски

ОТВЕТЫ

Ответ 1

Лично мы убеждаемся, что каждый открытый и защищенный метод имеет комментарии XML. Он также предоставит вам Intellisense, а не только справочную документацию для конечных пользователей. Раньше мы также включали его в объявления с закрытой областью, но не чувствуем, что это 100% требуется, если методы короткие и точечные.

Не забывайте, что есть инструменты, облегчающие вам задачи комментирования XML:

  • GhostDoc - надстройка наследования и шаблонов комментариев.
  • Sandcastle Help File Builder - Редактирует проекты Sandcastle через графический интерфейс, может запускаться из командной строки (для автоматизации сборки) и может отредактируйте MAML для справок, не связанных с кодом. (Версия 1.8.0.0 alpha очень стабильна и очень улучшена. Используете ее примерно месяц, более 1.7.0.0).

Ответ 2

Комментарии очень часто устаревают. Это всегда было проблемой. Мое эмпирическое правило: чем больше вам нужно работать для обновления комментария, тем быстрее этот комментарий будет устаревшим.

Комментарии XML отлично подходят для разработки API. Они отлично работают с Intellisens, и они могут заставить вас создать HTML-документ справки в кратчайшие сроки.

Но это не бесплатно: поддерживать их будет сложно (посмотрите на любой нетривиальный пример, вы поймете, что я имею в виду), поэтому они будут очень устаревшими. В результате просмотр комментариев XML должен быть добавлен в ваш обзор кода в качестве обязательной проверки, и эта проверка должна выполняться каждый раз, когда файл обновляется.

Ну, так как это дорого поддерживать, поскольку многие не частные символы (в разработке, отличные от API) используются только 1 или 2 классами, и поскольку эти символы часто не требуют пояснений, я бы никогда не применял правило, говоря, что каждый не-частный символ должен быть прокомментирован XML. Это будет чрезмерным и conterproductive. То, что вы получите, это то, что я видел во многих местах: почти пустой XML-комментарий, ничего не добавляющий к имени символа. И код, который является чуть менее читаемым...

Я думаю, что важная направляющая строка очень, очень о комментариях в нормальном (не-API) коде не должна быть о КАК их писать, но о ЧТО они должны содержать. Многие разработчики до сих пор не знают , что писать. Описание того, что должно быть прокомментировано с примерами, будет лучше для вашего кода, чем просто простой: "Используйте XML-комментарии для каждого не-частного символа".

Ответ 3

Я документирую публичные классы и общедоступные/защищенные члены этих классов.

Я не документирую частные или внутренние члены или внутренние классы. Следовательно, переменные (я думаю, вы имеете в виду поля), потому что они являются частными.

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

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

Ответ 4

Я очень редко комментирую переменные метода и в равной степени редко поля (поскольку они обычно покрываются свойством или просто не существуют при использовании автоматически реализованных свойств).

Обычно я стараюсь добавлять содержательные комментарии всем общедоступным/защищенным членам, что удобно, поскольку, если вы включаете комментарии xml во время сборки, вы получаете автоматические предупреждения о недостающих комментариях. В зависимости от сложности я мог бы не заполнять каждую деталь - то есть, если на 100% очевидно, что должен делать каждый параметр (т.е. Нет специальной логики, и есть только один логический способ интерпретации переменных), то я мог бы получить ленивый и не добавлять комментарии о параметрах.

Но я, конечно, пытаюсь описать, какие методы, типы, свойства и т.д. представляют/делают.

Ответ 5

Мы документируем публичные методы/свойства/etc в наших библиотеках. В рамках процесса сборки мы используем NDoc для создания веб-ссылки, подобной MSDN. Это было очень полезно для быстрой справки и поиска.

Это также отлично подходит для Intellisense, особенно с новыми членами команды или, как вы сказали, когда оригинальный автор ушел.

Я согласен с тем, что код, в общем, должен быть самоочевидным. Документ XML, для меня, больше касается ссылки и поиска, когда у вас нет открытого источника.

Ответ 6

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