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

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

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

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

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

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

6 ОТВЕТОВ
РЕШЕНИЕ

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

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

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

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

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

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

3
10.12.2008 13:18:55

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

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

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

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

4
10.12.2008 13:31:09

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

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

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

1
10.12.2008 13:35:38

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

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

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

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

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

7
19.02.2012 00:38:07

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

0
12.08.2010 11:44:04
Может показаться, что это больше работы, но есть комментарии для улучшения понимания кода, они должны быть частью вашей работы по обновлению кода и обновлению комментариев.
Jonathan Websdale 8.06.2012 09:01:05