Каковы достоинства использования XML-комментариев в.NET?
Я не могу понять достоинства использования XML-комментариев. Я знаю, что они могут быть преобразованы в хорошую документацию, внешнюю к коду, но то же может быть достигнуто с намного более кратким синтаксисом DOxygen. По-моему, XML-комментарии являются неправильными, потому что:
- Они запутывают комментарии и код в целом. (Их более трудно считать людьми).
- Меньше кода может быть просмотрено на одном экране, потому что "сводка" и "/сводка" проводит дополнительные строки.
- (удаленный)
Что затем, возможно, было быть причинами, почему XML был предпочтен в.NET скорее что простой синтаксис DOxygen?
6 ответов
На самом деле здесь нет правильного ответа, imo.На самом деле ни одна из систем не «лучше» другой - в конечном итоге они обе выполняют одну и ту же работу, что позволяет вам создавать документацию по коду.
Окончательный результат может быть отформатирован одинаково для каждого из них, и у них действительно есть примерно одинаковые функциональные возможности с точки зрения поддерживаемых ими меток и т. Д., Так что это действительно вопрос личного выбора.
Лично я считаю, что XML-комментарии гораздо более удобочитаемы, более логичны и просто просты в использовании - но это с дополнительным преимуществом, заключающимся в том, что визуальная студия автоматически генерирует заглушки, которые я могу просто заполнить, и отличная поддержка он предназначен для их сворачивания, чтобы они не занимали много места на экране. Я уверен, что кто-то из тех, кто занимается фоновым редактированием в VI или some_other_IDE, будет придерживаться другого мнения, но ни то, ни другое не дает реальных преимуществ.
Итак, я бы сказал, что на самом деле это зависит от того, какую IDE вы используете и что вы и ваша команда привыкли использовать.
Теперь, если вы спрашиваете, почему Microsoft решила так тесно интегрироваться с XML-комментариями в Visual Studio, это другой вопрос. Скорее всего, это связано с тем, что: им было бы проще реализовать в VS (поскольку они могут повторно использовать существующий код для генерации / чтения комментариев и создания intellisense и т. Д.), У них есть тенденция придерживаться "стандартов" "в любом случае (будь то собственное или отраслевое), а также причины лицензирования, упомянутые Джеффом.
Просто добавлю, что продукт, который Microsoft использует в VS, называется Sandcastle, это внутренний инструмент создания XML-документов.У него есть собственная вики-страница @ http://docproject.codeplex.com/Wikipage
- Ide подбирает комментарии и показывает их при использовании этого метода.
- Каждый, кто программирует на C #, вероятно, знаком с системой комментариев XML.Новичку можно научиться меньше.
Я не говорю, что DOxygen не лучше, просто система комментариев xml более знакома всем, и это имеет большое значение. Просто на одну вещь меньше, чем нужно обучать нового сотрудника.
Что касается оставления переменных без комментариев. То, что может быть очевидным для вас, не станет очевидным для кого-то другого (или для вас через 6 месяцев).
Хорошо, теперь я понимаю, о чем вы спрашиваете.
Непонятные комментарии. Цветовая кодировка помогает. Лично я быстро просматриваю серый текст и читаю только зеленый, если мне не нужно читать текст xml. (по крайней мере, в моих настройках).
У нас большие мониторы, поэтому мы обычно выводим на экран больше кода. (Дешевле купить большой монитор, чем вообще переучивать людей). Еще одна вещь, связанная с этим, заключается в том, что я уверен, что вы активно просматриваете только одну функцию за раз, поэтому, если вся эта функция умещается на странице, вы, вероятно, не слишком страдаете от того, что не видите больше кода. Теперь, если функции длинные, я могу видеть, что это проблема.
Мы помещаем итоговые комментарии в одну строку, когда это возможно (при условии, что она не очень большая). Это сокращает используемое пространство.
Я не знаю, делает ли это DOxygen, но вы можете свернуть комментарии, чтобы они не мешали.
что меня поразило еще больше, так это популярность плагина ghostdoc . Если вы можете автоматически сгенерировать комментарий на основе имени метода, зачем вообще нужен комментарий?
Стив Йегге говорит, что вместо комментирования - признак новичка в программировании, мне трудно не согласиться с его.
У вас нет , чтобы использовать их в своих проектах.
Это стандарт, который интегрируется в Visual Studio, и если вы используете StyleCop, их можно применить. Итак, это достоинство.
Однако, если вы решите использовать DOxygen, вас ничто не остановит. Просто убедитесь, что вы последовательны.
Преимущества использования комментариев XML в .NET
Они изначально поддерживаются компилятором C # и Visual Studio, обеспечивая единое место для документирования вашего API для использования в печатной, электронной и intellisense документации.
В этой статье из журнала MSDN говорится следующее:
В каждом проекте есть кто-то, недовольный документацией. Руководители группы хотят, чтобы в них было больше комментариев. источник, технические писатели хотят получить больше письменной информации о дизайне кода, отдел контроля качества хочет увидеть функциональные спецификации и т. Д. . Если все эти документы на самом деле написаны, вам все равно придется поддерживать их синхронизацию .
Хотя формат не обязательно идеален, комментарии к документации XML предоставляют богатый синтаксис, так что это может быть достигнуто.
Почему бы вместо этого не поддерживать DOxygen в C #?
Что касается того, почему существующая система XML была выбрана вместо DOxygen, я подозреваю, что это в первую очередь потому, что DOxygen выпущен под GPL ], что означало бы, что Visual Studio и компилятор C # также должны быть выпущены как таковые - что Microsoft, несомненно, не захочет делать, учитывая условия GPL .
Основная задача XML-документации - , а не создание документации. Он предназначен для предоставления хорошей информации о IntelliSense для клиента вашего класса. Отправьте сгенерированный XML-файл вместе со сборкой.