Каковы добродетели использования комментариев XML в .NET?

Question

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

1. Они запутают комментарии и код в целом. (Они труднее читать людьми).
2. Меньше кода можно просматривать на одном экране, потому что «Сводка» и «/ Резюме» принимают дополнительные строки.
3. (удаленный)

То, что тогда мог быть причины, почему XML предпочтительнее в .Net, скорее, что простой синтаксис Doxygen?

Answer 1

Здесь не очень правильный ответ IMO. Ни одна система не «лучше», чем другая на самом деле - они оба делают ту же работу в конце, что позволяет создавать документацию кода.

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

Лично я нахожу комментарии XML, чтобы быть гораздо более читаемым человеком, гораздо более логичным и просто простым в использовании - но это с добавленным преимуществом Visual Studio автоматически генерировать заглушки для меня, чтобы просто заполнить, и отличная поддержка, для которой он имеет для Расширяя их, чтобы они не забирают много места на экране. Я уверен, что кто-то, кто приходит от редактирования фона в VI или quote_other_ide, будет иметь другое мнение, но никакого реального преимущества.

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

Теперь, если вы спрашиваете, почему Microsoft решила интегрировать так плотно интегрировать XML комментирование в Visual Studio, это другой вопрос. Скорее всего, это связано с фактами, которые: для них было бы проще реализовать в VS (поскольку они могут повторно использовать существующий код для генерации / чтения комментариев и строить Intellisense etc), у них есть тенденция для придерживания «стандартов «В любом случае (будь то их собственные или отраслевые), а также лицензионные причины, как упомянутые Джеффом.

Просто добавить, что продукт Microsoft использует в VS, называется «Sandcastle», который является внутренним инструментом генерации XML DOC. У него есть своя страница Wiki @ http://docproject.codeplex.com/wikipage.

Answer 2

1. IDE поднимает комментарии и показывает их при использовании этого метода.
2. Каждый, кто программирует C #, вероятно, знаком с системой комментирования XML. Есть меньше, чтобы учиться нового проката.

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

Что касается переменных незаметных. Что может быть очевидно для вас, не будет кому-то еще (или к вам через 6 месяцев).

Хорошо, теперь я думаю, что вижу, что вы спрашиваете.

1. Запутанные комментарии. Цветовая кодировка помогает. Лично я быстро сканирую мимо серого текста и читаю только что зеленый, если мне не нужно читать текст XML. (По крайней мере, в моих настройках).

2. У нас есть большие мониторы, поэтому мы получаем больше кода на экране в целом. (Дешевле купить большой монитор, чем чтобы пожелание людей вообще). Другая вещь по этому поводу, в том, что я забиваю, вы активно смотрите на одну функцию одновременно, поэтому, если вся целая функция подходит на странице, вы, вероятно, не слишком сильно страдаете от того, что не вижу большего количества кода. Теперь, если функции длинные, то я мог видеть, что это проблема.

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

4. Я не знаю, делает ли это doxygen, но вы можете свернуть комментарии, чтобы они были в пути.

Answer 3

Основная задача документации XML нет генерировать документацию. Это для обеспечения хорошей информации Intellisense для клиента вашего класса. Отправьте сгенерированный файл .xml вместе с вашим сборкой.

Answer 4

Добродетели использования комментариев XML в .NET

Они вначале поддерживаются C # Compiler и Visual Studio, предоставляя одно местоположение для документирования вашего API для использования в печатном, онлайн-документации и Intellibense.

Эта статья из журнала MSDN утверждают следующее:

В каждом проекте есть кто-то, кто не доволен документацией. Команда ведет желание больше комментариев в источнике, технические писатели хотят более написанную информацию о дизайне кода, гарантия качества хочет увидеть функциональные спецификации и так далее. Если все эти документы на самом деле написаны, у вас все еще есть битва, когда все они синхронизированы.

Хотя формат не обязательно является идеальным, документация XML Комментарии предоставляют богатый синтаксис такой, что это может быть достигнуто.

Почему бы не поддерживать Doxygen в C # вместо этого?

Что касается того, почему существующая система XML была выбрана над Doxygen, я бы подозреваю, что это в первую очередь, потому что Doxygen. выпущен под Овладение что означало бы визуальную студию и компилятор C # также должны быть выпущены как таковые - то, что Microsoft, несомненно, не хочет делать рассмотрение Сроки GPL.

Answer 5

То, что я нахожу еще больше, - это популярность Ghostdoc. плагин. Если вы можете автоматически генерировать комментарий на основе имени метода, зачем вообще комментарий?

Стив Еггей говорит, что за комментарию Является ли признак Newbie Programmer, мне трудно не оказание с ним.

Answer 6

Вы не имеют использовать их в ваших проектах.

Они есть а. Стандарт, который будет включен в Visual Studio, и если вы используете StyleCop, они могут быть применены. Так что это добродетель здесь.

Однако, если вы решите, что хотите использовать Doxygen, то вас ничего не останавливает. Просто убедитесь, что вы согласуетесь.