Каковы преимущества использования XML-комментариев в .NET? - PullRequest
9 голосов
/ 06 апреля 2010

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

  1. Они запутывают комментарии и код в целом. (Их труднее читать людям).
  2. Меньше кода можно просмотреть на одном экране, потому что "summary" и "/ summary" занимают дополнительные строки.
  3. (удалено)

В чем тогда могут быть причины, почему XML предпочтен в .NET, а не простой синтаксис DOxygen?

Ответы [ 6 ]

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

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

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

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

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

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

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

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

7 голосов
/ 06 апреля 2010

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

4 голосов
/ 06 апреля 2010

Преимущества использования XML-комментариев в .NET

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

В этой статье из журнала MSDN говорится следующее:

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

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

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

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

3 голосов
/ 06 апреля 2010

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

Стив Йегге говорит, что из-за комментариев - признак новичка-программиста, мне трудно с ним не согласиться.

1 голос
/ 06 апреля 2010

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

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

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

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

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

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

1 голос
/ 06 апреля 2010

У вас нет , чтобы использовать их в своих проектах.

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

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

...