Советы по комментированию XML для программирования на C # [закрыты]

Question

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

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

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

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

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

Answer 1

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

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

• Призрачный документ - Наследование комментариев и надстройка для создания шаблонов.
• Конструктор файлов справки Sandcastle - Редактирует проекты Sandcastle с помощью графического интерфейса, может запускаться из командной строки (для автоматизации сборки) и может редактировать MAML для разделов справки, не производных от кода.(Альфа-версия 1.8.0.0 очень стабильна и значительно улучшена.Пользуюсь им уже около месяца, версия 1.7.0.0)

Answer 2

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

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

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

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

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

Answer 3

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

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

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

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

Answer 4

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

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

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

Answer 5

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

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

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

Answer 6

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