Comments 73
Все время считал это фичей VS, а оказалось входит в язык :)
Да, причем из дотнетовских только в C#
неправда: msdn.microsoft.com/en-us/library/ms172653(VS.80).aspx
Я знал об этом, но каюсь: не документирую код.
Автор, спасибо! После этой статьи я начал проводить полную документацию своих проектов. Сижу вот, описываю =)
Раньше почему-то не мог собраться с мыслями и не начинал документировать (((
Автор, спасибо! После этой статьи я начал проводить полную документацию своих проектов. Сижу вот, описываю =)
Раньше почему-то не мог собраться с мыслями и не начинал документировать (((
Спасибо, очень познавательно. Хорошо бы побольше статей по фичам студии.
Хотел недавно написать про сниппеты, но про них уже писали, если не читали — почитайте, полезная штука. Я, в свою очередь, постараюсь описать еще некоторые фичи этой чудесной IDE
Про сниппеты читал, но как-то они у меня не прижились. Надо заставлять себя, это действительно удобно, но пока привычка их использовать не появилась.
Буду ждать дальнейших статей от вас =)
Буду ждать дальнейших статей от вас =)
Я из сниппетов пользуюсь только ctor, наверное :)
Нужно посмотерть что ещё полезного и частоиспользуемого там есть.
Нужно посмотерть что ещё полезного и частоиспользуемого там есть.
Там много чего есть =) Да еще и свои создавать можно. Буду привыкать к ним, полюбому.
Веб-разработчикам, наверное, будет полезен eventh так же как и мне.
ИМХО — XML неудобен для человека. Мне тяжело даже phpDoc писать((
Хоть бы нормальное что-нибудь придумали, а то руки отваливаются всякие @param писать((
Хоть бы нормальное что-нибудь придумали, а то руки отваливаются всякие @param писать((
Удобства проявляются потом, кода пользуешься задокументированными таким образом библиотеками. К тому же в этих комментариях работает IntelliSense, буковками приходится писать только по делу.
По поводу удобства для человека — это все потом можно перевести в файлики mht (вроде так называются) и получить документацию как в msdn, что вполне удобно для человека.
И если заговорили про нормально. Как вам это видится? Какой формат придумать чтобы можно было описать все эти данные и в тоже время совсем не напрягаться?
По поводу удобства для человека — это все потом можно перевести в файлики mht (вроде так называются) и получить документацию как в msdn, что вполне удобно для человека.
И если заговорили про нормально. Как вам это видится? Какой формат придумать чтобы можно было описать все эти данные и в тоже время совсем не напрягаться?
установите себе VisualAssist или Resharper они облегчат создание XML комментариев до одного клика.
установите себе VisualAssist или Resharper они облегчат создание XML комментариев до одного клика.
не подскажите, какой клик и куда надо сделать в ReSharper? с ходу не нашел
Перед телом метода или класса просто наберите три слеша, и R# вставит шаблон комментария.
это я знал
вопрос в том, как мышью это провернуть «в один клик», так как озвучил name1ess0ne
вопрос в том, как мышью это провернуть «в один клик», так как озвучил name1ess0ne
Это вставляет VS2008, решарпер вроде не при чем. Хотя может эта фича просто пересекается. А в один клик у меня получается генерить такие комменты в R# 4.1 просто нажав на название метода, слева появляется «лампочка», по ней уже щелкаем и выбираем «generate xml comments». Но тут нужно, чтобы отсутствие этих комментариев вызывало Warnings при компиляции. По-моему, так.
Подробнее о настройках смогу посмотреть попозже.
Подробнее о настройках смогу посмотреть попозже.
Мышью в один клик это делается в VisualAssist, которым я и пользуюсь. Но и в Resharper есть функциональность для вставки XML комментариев, разве не так?
Кстати вот что еще нашел, думаю многим пригодится.
www.roland-weigelt.de/ghostdoc/
Кстати вот что еще нашел, думаю многим пригодится.
www.roland-weigelt.de/ghostdoc/
Если нужны только комментарии, то GhostDoc поможет:
www.roland-weigelt.de/ghostdoc/
На методе правой кнопкой и клик по «Document this». GhostDoc многое напишет за Вас. :)
www.roland-weigelt.de/ghostdoc/
На методе правой кнопкой и клик по «Document this». GhostDoc многое напишет за Вас. :)
лучше GhostDoc.
Он по нажатию Cntrl+D+D Автоматически документирует выбранный код и даже описание пытается составить на основе названия метода. (и если в названиях придерживаться правила — только глаголы — даже нормально получается у него :) )
Он по нажатию Cntrl+D+D Автоматически документирует выбранный код и даже описание пытается составить на основе названия метода. (и если в названиях придерживаться правила — только глаголы — даже нормально получается у него :) )
Соглашусь. Для меня тоже xml менее читаем чем олд-скул javadoc/phpdoc-комментарии.
У нас в компании есть специальная тулза. Её нужно запускать перед тем, как сабмитить код в систему контроля версий. Она правит проекты в Sollution, изменяя настройки таким образом, что все Warning выскакивают ошибками, и компиляция не проходит. А предупреждения вставляются на такие вещи как: отсутствие XML документации к не private методам, наличие неиспользуемых переменных и т. д. Поначалу непривычно писать, потом привыкаешь, но зато в репозиторий уже попадают коды в очень хорошем виде.
Хотя я на этапе разработки предпочитаю отключать эту фичу, а документировать все что сделал уже перед сабмитом на сервер.
Хотя я на этапе разработки предпочитаю отключать эту фичу, а документировать все что сделал уже перед сабмитом на сервер.
А что за тулза такая? Порекомендуйте =)
Кем-то из сотрудников написанная много лет назад, так что тут врядли порекомендовать смогу :) Завтра посмотрю детальнее что она в проектах меняет, расскажу.
Только сразу предупреждаю, могу забыть :)
Только сразу предупреждаю, могу забыть :)
Спасибо, очень интересно.
PS Я вам напомню, если что ;)
PS Я вам напомню, если что ;)
а исходники есть? :)
Может того её, в опенсорц? :)
Может того её, в опенсорц? :)
Я даже не знаю, мне досталась как инсталлятор. Теоретически где-то в хранилище должны быть и сорцы, но сомневаюсь, что найду :)
Да сама программа в общем-то тупа по своей логике, скорее всего берет открытый Sollution, проходится по всем Project которые ему принадлежат и правит ихние настройки. Эти же файлы в виде XML хранятся. Студия после её запуска ещё говорит о том, что Project изменен внешней программой, перезагрузить или оставить таким как есть.
Завтра выйду на работу — посмотрю. А то в обещаную пятницу закрутился и вспомнил только дома об этом :)
Да сама программа в общем-то тупа по своей логике, скорее всего берет открытый Sollution, проходится по всем Project которые ему принадлежат и правит ихние настройки. Эти же файлы в виде XML хранятся. Студия после её запуска ещё говорит о том, что Project изменен внешней программой, перезагрузить или оставить таким как есть.
Завтра выйду на работу — посмотрю. А то в обещаную пятницу закрутился и вспомнил только дома об этом :)
Оценил всю прелесть и крутость XML-комментариев в C#, когда писал диплом. С автором согласен.
Есть удобный plugin для Visual Studio, называется GhostDoc. Умеет сам генерировать комментарии в соответствии с названием методов. Можно делать шаблоны и т. д. Очень удобно.
отличная штука, а решарпер еще потом приглядывает если что то убрано или не добавлено в коммент.
www.roland-weigelt.de/ghostdoc/
Просто жмете на название метода/класса/функции/интерфейса и пр. правой кнопкой мыши и выбираете первый пункт: Document This :)
www.roland-weigelt.de/ghostdoc/
Просто жмете на название метода/класса/функции/интерфейса и пр. правой кнопкой мыши и выбираете первый пункт: Document This :)
XML-документирующие комментарии? Похоже на стремление впихнуть как можно больше buzzword'ов в продукт. :)
на этапе компиляции можно сгенерировать XML файл, который будет содержать все комментарии в удобном формате, а с этим файлом уже можно сделать все что угодно.
Это не только «можно», но и «нужно». Если поставлять проект в виде скомпилированной .NET-сборки и ссылаться на нее через Add Reference, то для того, чтобы IntelliSense мог что-то показать, рядом с этой сборкой должен лежать тот самый XML-файл.
Отказался от XML-комментариев в пользу doxygen-style. Теги XML очень сильно загромождают код. Правда, пришлось соответственно и отказаться от поддержки VS для автогенерации тегов, tooltip'ов и т. д. Однако для меня такой комментарий
более понятен, нежели
/** Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
* @param [in] repeat Сколько раз передать привет
* @return Сама строка с приветами
*/
более понятен, нежели
/// <summary>
/// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
/// </summary>
/// <param name="repeat">Сколько раз передать привет</param>
/// <returns>Сама строка с приветами</returns>
А для меня наоборот. Глаз уже «намётан» давно и я эти "///" комментарии понимаю «сполуслова».
ЛЮДИ, ПИШИТЕ КАМЕНТЫ:
1) это в разы облегчает поддержку кода;
2) сокращает количество комментариев внутри метода (потому что все поля и вызываемые методы подсвечиваются подсказкой, где написано предназнаение члена класса, как на скринах сверху). Вобщем комментарии внутри метода остаются только в случае нестандартности или «не с первого взгляда» интуитивности, как иногда случается в каверзных ситуациях.
Пишите каменты и на ВСЕ поля, и на ВСЕ классы, а не только на методы.
Мне даже при написании класса (особенно средней и выше сложности) каменты уже оказывают значительную помощь — я не теряюсь в 5 методах, например.
P.S. Очень тяжело читать C# open source без каментов, попробуйте подфиксить внутренности хотя бы QuickGraph или DockPanel Suite и вы сразу поймете для чего те комментарии нужны!
ЛЮДИ, ПИШИТЕ КАМЕНТЫ:
1) это в разы облегчает поддержку кода;
2) сокращает количество комментариев внутри метода (потому что все поля и вызываемые методы подсвечиваются подсказкой, где написано предназнаение члена класса, как на скринах сверху). Вобщем комментарии внутри метода остаются только в случае нестандартности или «не с первого взгляда» интуитивности, как иногда случается в каверзных ситуациях.
Пишите каменты и на ВСЕ поля, и на ВСЕ классы, а не только на методы.
Мне даже при написании класса (особенно средней и выше сложности) каменты уже оказывают значительную помощь — я не теряюсь в 5 методах, например.
P.S. Очень тяжело читать C# open source без каментов, попробуйте подфиксить внутренности хотя бы QuickGraph или DockPanel Suite и вы сразу поймете для чего те комментарии нужны!
Даёшь самодокументирующийся код!
Хватит захламлять код!
Хватит захламлять код!
Самодокументирующийся код — это действительно клёво, но это нужно при совместной работе надо одним кодом группы людей. XML-документация — это другое. Это те подсказки, что мы должны оставлять для тех, кто не полезет в исходники наших уже готовых сборок, а будет просто линковать их и использовать, реализованные там типы. Не всякий же раз, используя тип из внешней сборки, полезешь буравить его код рефлектором… Как-то так :-)
Ну, да. Вот объясни мне зачем этот камент:?? Вот какая от него польза?
Как эта функция должна называться в самодокументирующемся коде
void printHelloHabrNumberOfTimes(int number)
Сравни вот с этим — где больше «информационного шума»?
/// /// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
///
/// Сколько раз передать привет
Как эта функция должна называться в самодокументирующемся коде
void printHelloHabrNumberOfTimes(int number)
Сравни вот с этим — где больше «информационного шума»?
/// /// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
///
/// Сколько раз передать привет
а я бы обозвал параметр метода как int times
согласен.
вот этому и надо учиться, чтобы выбирать однозначные и для всех понятные именна для классов, методов, переменных
вот этому и надо учиться, чтобы выбирать однозначные и для всех понятные именна для классов, методов, переменных
именно поэтому его нужно документировать :)
Это только русский язык такой удобный, что можно слово в родительном падеже использовать в качестве названия с малой вероятностью появления неоднозначности. Других «times» заставит лишний раз задуматься «какие такие времена?», «это что, массив/список?» и т. д.
Иных разрабов хочется заставить комментировать по-русски латинскими буквами (int raz), либо вообще сослать на 1С. :)
Иных разрабов хочется заставить комментировать по-русски латинскими буквами (int raz), либо вообще сослать на 1С. :)
А как тогда будет называться входной параметр в случае, если допустимо, чтобы он принимал значения от 1 до 10? ;-)
Это все понятно, но писать в лог — это все как дополнительные вещи. Зачем мне писать метод в коде, вызывать его, смотреть что результат не ожидаемый вышел, лезть в лог и смотреть в чем ошибка, потом только исправлять её. Проще посмотреть сразу при написании кода какие допустимые значения.
Другой вопрос. А куда этот метод пишет? В файл, в лог, в консоль, в Response.OutputStream? Останется известным только вам.
И опять же. Если вы сгенерируете потом нормальную документацию из этого, то другие разарботчики смогут без проблем её читать, иметь представление что и как работает, для чего все нужно, а потом уже начнуть писать код. Без такой же документации все придется делать методом тыка.
И ещё, какие исключения этот метод может сгенерировать? InvalidArgumentException, IoException? Или может какое-то свое исключение? Не перехватывать же базовый Exception.
В общем, писать или не писать комментарии зависит от нескольких вещей. Будет ли кто-то кодом работать ещё, планируется ли это выкладывать в общее пользование, насколько вероятна поддержка кода в будущем. Я для своих каких-то целей когда пишу, то xml комментариями не пользуюсь, а на работе всегда так пишу и понимаю, что не зря.
А с названиями методов вы правы на 100%, их такими нужно давать как при наличии xml-comments так и без них :) Не комментариями едиными.
Другой вопрос. А куда этот метод пишет? В файл, в лог, в консоль, в Response.OutputStream? Останется известным только вам.
И опять же. Если вы сгенерируете потом нормальную документацию из этого, то другие разарботчики смогут без проблем её читать, иметь представление что и как работает, для чего все нужно, а потом уже начнуть писать код. Без такой же документации все придется делать методом тыка.
И ещё, какие исключения этот метод может сгенерировать? InvalidArgumentException, IoException? Или может какое-то свое исключение? Не перехватывать же базовый Exception.
В общем, писать или не писать комментарии зависит от нескольких вещей. Будет ли кто-то кодом работать ещё, планируется ли это выкладывать в общее пользование, насколько вероятна поддержка кода в будущем. Я для своих каких-то целей когда пишу, то xml комментариями не пользуюсь, а на работе всегда так пишу и понимаю, что не зря.
А с названиями методов вы правы на 100%, их такими нужно давать как при наличии xml-comments так и без них :) Не комментариями едиными.
1. Если вы думаете, что все кто пишет код постоянно смотрят на quick help, то вы глубоко ошибаетесь.
2. Лог всегда пишет в лог.
3. Я вам дал нормальный вариант как ограничить ввод данных другим способом — используйте enum, передавайте всё это дело в классе-обёртке.
4. Если это настолько кртитично, то киньте свой exception, типа InvalideRangeException.
2. Лог всегда пишет в лог.
3. Я вам дал нормальный вариант как ограничить ввод данных другим способом — используйте enum, передавайте всё это дело в классе-обёртке.
4. Если это настолько кртитично, то киньте свой exception, типа InvalideRangeException.
Мне кажется 99% людей, кто пользуется новой какой-то библиотекой смотрят на подсказки в IntelliSense, что делают функции, зачем те или иные параметры… У меня Ctrl + Shift + Space одно из самых частоиспользуемых сочетаний клавиш.
Не спорю что лог пишет туда, но зачем мне узнавать о причине ошибки в рантайме, если я могу её предотвратить на этапе написания?
Число принимаемое может быть ограничено по определенному диапазону. На них перечислений не напасешься.
Я о своем исключении и писал. Вот только если это мой класс будет, как вы узнаете как он называется? Опять в рантайме?
Я понимаю, что писать эту всю документацию лениво, но не могу понять вашу категоричную точку зрения. Я когда начал работать с jquery, то подключил для него IntelliSense с описанием всех методов и параметров. Таким образом получилось писать сразу, практически не обращаясь ко всяким справочникам. Мне нравится пользоваться хорошо написанным кодом, поэтому стараюсь делать такой же для других.
Не спорю что лог пишет туда, но зачем мне узнавать о причине ошибки в рантайме, если я могу её предотвратить на этапе написания?
Число принимаемое может быть ограничено по определенному диапазону. На них перечислений не напасешься.
Я о своем исключении и писал. Вот только если это мой класс будет, как вы узнаете как он называется? Опять в рантайме?
Я понимаю, что писать эту всю документацию лениво, но не могу понять вашу категоричную точку зрения. Я когда начал работать с jquery, то подключил для него IntelliSense с описанием всех методов и параметров. Таким образом получилось писать сразу, практически не обращаясь ко всяким справочникам. Мне нравится пользоваться хорошо написанным кодом, поэтому стараюсь делать такой же для других.
В любых IDE такая комбинация как «Ctrl + Shift + Space» выдаёт сигнатуру метода, а уж никак не описание ограничения каждого параметра.
Давайте так, что более юзабельно
/// <summary>
/// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
/// </summary>
/// <param name=«repeat»>Сколько раз передать привет</param>
/// <returns>Сама строка с приветами
public string foo(int i)
{
string result = "";
for (int i = 0; i < repeat; i++)
{
result += «Hello, HabraHabr!\n»;
}
return result;
}
Или void printHelloHabrNumberOfTimes(int number)?
Теперь по поводу библиотек. Библиотека для того и создаётся, чтобы использоватеться всеми по полной. В отличае от коментирования метода, который скорее всего вызоветься вами один раз и всё! Вы потратите больше времени на написание комента, чем полезного кода.
Давайте так, что более юзабельно
/// <summary>
/// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
/// </summary>
/// <param name=«repeat»>Сколько раз передать привет</param>
/// <returns>Сама строка с приветами
public string foo(int i)
{
string result = "";
for (int i = 0; i < repeat; i++)
{
result += «Hello, HabraHabr!\n»;
}
return result;
}
Или void printHelloHabrNumberOfTimes(int number)?
Теперь по поводу библиотек. Библиотека для того и создаётся, чтобы использоватеться всеми по полной. В отличае от коментирования метода, который скорее всего вызоветься вами один раз и всё! Вы потратите больше времени на написание комента, чем полезного кода.
Зачем вы в крайности? Я ещё в первом комментарии написал
Одно не противоречит другому. Вы ведь видели в сигнатуре каждого метода, описание отдельного параметра? Там можно писать и об ограничениях. В описании метода можно указать какие исключения он вызывает. И пользуясь такими «сигнатурами», вы получаете исчерпывающую информацию о вызываемом методе.
Я вот просто сейчас вижу, что вы немного не о тех вещах говорите. Вы правильно поняли, как xml-comments работают? Это в первую очередь нужно не для того, чтобы вы не понимал из вот этого в коде за что метод отвечает
А для того, чтобы вашими библиотеками потом было удобно пользоваться всем и по полной, с привильно описаными сигнатурами методов и так далее. И этот ваш труд в комментариях ещё как оценен будет.
На сим со своей стороны беседу останавливаю, так как вижу что мы или в разных плоскостях рассуждаем, или говорим о разных вещах, так как не сходимся во мнениях.
Вы к стати на C# работаете?
А с названиями методов вы правы на 100%, их такими нужно давать как при наличии xml-comments так и без них
Одно не противоречит другому. Вы ведь видели в сигнатуре каждого метода, описание отдельного параметра? Там можно писать и об ограничениях. В описании метода можно указать какие исключения он вызывает. И пользуясь такими «сигнатурами», вы получаете исчерпывающую информацию о вызываемом методе.
Я вот просто сейчас вижу, что вы немного не о тех вещах говорите. Вы правильно поняли, как xml-comments работают? Это в первую очередь нужно не для того, чтобы вы не понимал из вот этого в коде за что метод отвечает
/// <summary> /// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите. /// </summary> /// <param name=«repeat»>Сколько раз передать привет</param> /// <returns>Сама строка с приветами
А для того, чтобы вашими библиотеками потом было удобно пользоваться всем и по полной, с привильно описаными сигнатурами методов и так далее. И этот ваш труд в комментариях ещё как оценен будет.
На сим со своей стороны беседу останавливаю, так как вижу что мы или в разных плоскостях рассуждаем, или говорим о разных вещах, так как не сходимся во мнениях.
Вы к стати на C# работаете?
Ну отныне комментарии писать станет даже интереснее
Такие комментарии генереируются в VB.NET если ввести три апострафа
Такие комментарии генереируются в VB.NET если ввести три апострафа
Отличная возможность. А для генерации документации по XML-комментариям можно использовать тулзу Sandcastle от MS и Sandcastle Help File Builder (графическая оболочка для Sandcastle).
В SharpDevelop, кстати, тоже очень неплохая помогалка для генерации документирующих комментариев.
FAQ по документирующим комментариям в C#
rsdn.ru/article/devtools/CSxmlcmnt.xml
Sandcastle — Новый генератор документации для .NET
rsdn.ru/article/helpsystems/Sandcastle.xml
rsdn.ru/article/devtools/CSxmlcmnt.xml
Sandcastle — Новый генератор документации для .NET
rsdn.ru/article/helpsystems/Sandcastle.xml
Автору спасибо. Забыли только упомянуть о коментах в .js коде, благо 2008 студия уже их прекрасно поддерживает и воспроизводит.
Вставлю свои пять копеек.
list — это не просто список. У него может быть тип (type = bullet|table). item — элементы списка, внутри них можно ещё использовать term — description.
Минус: Object Browser не отупляет такие конструкции — выводит всё одной строкой без разделителей даже.
Плюсы: R# (Ctrl + Q) и Sandcastle отупляют :)
list — это не просто список. У него может быть тип (type = bullet|table). item — элементы списка, внутри них можно ещё использовать term — description.
<para>Структура таблицы:</para>
<list type="table">
<listheader>
<term>Название</term>
<description>Описание</description>
</listheader>
<item><term>user_id</term><description>Int32. Идентификатор пользователя.</description></item>
<item><term>user_name</term><description>String. Имя пользователя.</description></item>
</list>
Минус: Object Browser не отупляет такие конструкции — выводит всё одной строкой без разделителей даже.
Плюсы: R# (Ctrl + Q) и Sandcastle отупляют :)
Оказывается в CDS/BDS (Delphi 2005-2009) это тоже есть. Приятно удивлен.
Можете меня пинать, но все это было еще аж для VS2003, причем там был даже пункт типа Create HTML Documentation или что-то вроде того. Почему его убрали в 2005 и 2008 мне лично не понятно.
А чем вызван такой ажиотаж я вообще понять не могу. Про это в каждой книге Троелсена написано.
А чем вызван такой ажиотаж я вообще понять не могу. Про это в каждой книге Троелсена написано.
Sign up to leave a comment.
XML документация в C#