Комментарии 29
отлично! спасибо
Спасибо за очень подробное описание. Сразу сходил посмотреть, что за компоненты продаете :) Они кормят или это так, подработка?
отличное описание! спасибо, многие моменты уже забыл)
Исчерпывающе. Спасибо.
ваши слова, да многим разработчикам в уши… с первого курса!
Ну ни одна маленькая/средняя компания не хочет писать не то, чтобы документацию или структуру программы, а банальные комментарии ко всему коду и форматировать его.
Как можно скорость разработки продукта и скорость «вхождения» в проект для новых девелоперов променять на ленивое «программист должен кодить, а не программировать» или «а зачем комментарии, тут же и так все понятно» ??!!!
Дико…
Сегодня глаза сломал разбираясь в каше двухлетней давности какого-то кодера.
Ну ни одна маленькая/средняя компания не хочет писать не то, чтобы документацию или структуру программы, а банальные комментарии ко всему коду и форматировать его.
Как можно скорость разработки продукта и скорость «вхождения» в проект для новых девелоперов променять на ленивое «программист должен кодить, а не программировать» или «а зачем комментарии, тут же и так все понятно» ??!!!
Дико…
Сегодня глаза сломал разбираясь в каше двухлетней давности какого-то кодера.
За всех то не говорите. У нас, например по форматированию кода суровые правила — к SVN-у прикручен StyleCop (в нем задаётся шаблон по форматированию кода)
И криво отформатированный код разработчик даже не сможет закоммитить :)
Возможно о работе такой связки позже статейку напишу
И криво отформатированный код разработчик даже не сможет закоммитить :)
Возможно о работе такой связки позже статейку напишу
С удовольствием прочитал бы про связку SVN и StyleCop. То есть по-отдельности я их использую, а вместе пока не доводилось. Насколько понимаю, там используются хуки SVN?
Еще интересно, будет ли ваш подход работать на svn-хостингах типа code.google.com.
Еще интересно, будет ли ваш подход работать на svn-хостингах типа code.google.com.
Обязательно напишите такую статью. Очень интересно.
за всех и не говорю ('… да многим разработчикам ...').
Радостно, что есть фирмы, в которых к разработке подходят серьезно
Радостно, что есть фирмы, в которых к разработке подходят серьезно
НЛО прилетело и опубликовало эту надпись здесь
Этот файл уже сам по себе полезен тем, что если его положить рядом со сборкой (вашей dll), то это позволит функции IntelliSense в Visual Studio отображать описания для методов в момент набора пользователем кода.
А мне казалось, что для этого не нужно прикладывать файл с xml-комментариями…
Добавлю, что при включении генерации файла xml-документации, компилятор (по крайней мере C#) начинает генерировать warning'и на все публичные элементы без xml-комментариев. Довольно удобно.
GhostDoc не продвинулся в плане тега Exception?
/// Thrown when...
public void DoSomething() {… }
Всегда хотел какие-нибудь средства автоматически-полуавтоматически описать исключения гененируемые методом
/// Thrown when...
public void DoSomething() {… }
Всегда хотел какие-нибудь средства автоматически-полуавтоматически описать исключения гененируемые методом
парсер тег сожрал… в общем отсюда msdn.microsoft.com/en-us/library/w1htk11d.aspx
К сожалению, в плане автоматического прописывания исключений в GhostDoc ничего не поменялось.
Я сам очень хочу найти способ автоматически документировать исключения.
Я сам очень хочу найти способ автоматически документировать исключения.
У нас принято использовать синтаксис комментариев совместимый с Doxygen
Это обеспечивает единообразие стилей и способов генерации документации на разных платформах и языках.
Это обеспечивает единообразие стилей и способов генерации документации на разных платформах и языках.
Выскажу свое мнение.
Я вот лет 5 назад тоже увидел эту программулину и давай сразу тыкать, применять для всего. Но потом задумался — а кому нафик нужна эта автоматически сгенеренная документация? Особенно если там нет внятных примеров использования кода а всего по 2-3 очевидных объяснения к методу, которые можно и так понять из его названия.
Даже проводил соц. опрос среди разработчиков: полезна эта документация всего 10% разработчиков.
Ну сами подумайте. Скачали какую-нибудь либу. Открываете папку — там 150 Кб либа и 2 Мб документации. В документации только названия методов и очевидное их описание. Ну какой смысл в ТАКОЙ документации? Станете ли вы ее читать?
Нужна документация иного рода, где описывается процесс использования в общем + приведены конкретные примеры. И поменьше воды.
Мне гораздо полезнее примеры использования. Вот на это стоит потратить время. А заниматься пустотой смысла нет. То что так делают все — это не повод транжирить время.
Я вот лет 5 назад тоже увидел эту программулину и давай сразу тыкать, применять для всего. Но потом задумался — а кому нафик нужна эта автоматически сгенеренная документация? Особенно если там нет внятных примеров использования кода а всего по 2-3 очевидных объяснения к методу, которые можно и так понять из его названия.
Даже проводил соц. опрос среди разработчиков: полезна эта документация всего 10% разработчиков.
Ну сами подумайте. Скачали какую-нибудь либу. Открываете папку — там 150 Кб либа и 2 Мб документации. В документации только названия методов и очевидное их описание. Ну какой смысл в ТАКОЙ документации? Станете ли вы ее читать?
Нужна документация иного рода, где описывается процесс использования в общем + приведены конкретные примеры. И поменьше воды.
Мне гораздо полезнее примеры использования. Вот на это стоит потратить время. А заниматься пустотой смысла нет. То что так делают все — это не повод транжирить время.
Я некоторое время назад был склонен думать как вы. Но теперь изменил свое мнение.
Дело ведь в том насколько полна документация, а не в том, чем она сгенерирована. MSDN вот тоже автоматически генерируется и разве можно сказать, что эта документация не нужна?
Примеры использования и все прочее никто не запрещает создавать. Эта информация нужна и полезна. Дело как раз в том, что одно не исключает другого и документация, созданная из комментариев в исходниках, легко может быть дополнена примерами и какими-то еще описаниями.
Можете поискать в гугле LibTiff.Net. Это опенсоурсная библиотека, для которой документация сделана описанным в статье способом. Насколько получившаяся документация (а она содержит в том числе примеры использования) полезна — решать вам. Может быть ваше мнение по поводу такого способа документирования изменится.
Дело ведь в том насколько полна документация, а не в том, чем она сгенерирована. MSDN вот тоже автоматически генерируется и разве можно сказать, что эта документация не нужна?
Примеры использования и все прочее никто не запрещает создавать. Эта информация нужна и полезна. Дело как раз в том, что одно не исключает другого и документация, созданная из комментариев в исходниках, легко может быть дополнена примерами и какими-то еще описаниями.
Можете поискать в гугле LibTiff.Net. Это опенсоурсная библиотека, для которой документация сделана описанным в статье способом. Насколько получившаяся документация (а она содержит в том числе примеры использования) полезна — решать вам. Может быть ваше мнение по поводу такого способа документирования изменится.
Наверное зависит от того, будете ли вы для каждого метода приводить примеры и полезное описание. Иначе получается слишком много воды, а это плохо. Кто будет открывать и просматривать всем члены всех классов, дабы найти те 3-4 нещастных метода, где вы разместите примеры?
Просмотрел LibTiff.Net. Красота! Глаз нельзя отвести, как красиво. И себе захотелось так сделать… А вот толку — нуль (я имею в виду та часть, где неймспейсы и классы, а не где примеры и общее описание). Реально, если бы я использовал их библиотеку — мне бы были интересны лишь примеры и общее описание. Остальное легче глянуть в intellisense.
Ну разве что для красоты, для «крутости» имеет смысл это сделать. Чтоб же все видели, что я таки не отстаю от жизни и как все делаю абсолютно никому не нужную автогенеренную документацию (это ж круто!).
И еще одно. MSDN врядли писалась прямо в коде .Net. Это не удобно. Все примеры, все примечания туда втулить. У них наверняка более удобный инструмент. Вот от чего-либо подобного я б не отказался. А автогенеренная документация ТОЛЬКО по коду — не есть гуд. Тем более как ее переводить на другие языки?
Просмотрел LibTiff.Net. Красота! Глаз нельзя отвести, как красиво. И себе захотелось так сделать… А вот толку — нуль (я имею в виду та часть, где неймспейсы и классы, а не где примеры и общее описание). Реально, если бы я использовал их библиотеку — мне бы были интересны лишь примеры и общее описание. Остальное легче глянуть в intellisense.
Ну разве что для красоты, для «крутости» имеет смысл это сделать. Чтоб же все видели, что я таки не отстаю от жизни и как все делаю абсолютно никому не нужную автогенеренную документацию (это ж круто!).
И еще одно. MSDN врядли писалась прямо в коде .Net. Это не удобно. Все примеры, все примечания туда втулить. У них наверняка более удобный инструмент. Вот от чего-либо подобного я б не отказался. А автогенеренная документация ТОЛЬКО по коду — не есть гуд. Тем более как ее переводить на другие языки?
Можно включить файл проекта (*.shfbproj) от Sandcastle Help File Builder в solution Visual Studio, однако в настоящее время нет возможности использовать его как полноценный проект.
Вроде есть вот такой полноценный проект для VS, который генерирует документацию с помощью Sandcastle: docproject.codeplex.com/
Годика этак четыре назад писал статью про Sandcastle:
rsdn.ru/article/helpsystems/Sandcastle.xml
rsdn.ru/article/helpsystems/Sandcastle.xml
А еще если написать тройной слеш (///) Visual Studio сама вставит теги (summary, params, return) и останется только добавить для них описание.
Активно пользуюсь вашей статьей для старта с Sandcastle, а заодно и документацией к docotic, в качестве живого примера — спасибо!
Однако в большинстве случаев сгенерированный xml-файл содержит комментарии к внутренним структурам, которые пользователям не нужно или нельзя видеть. Ниже я напишу, как автоматически очистить xml-файл так, чтобы в нем остались только описания к публичным методам.
Может не внимательно читал, но чето не нашел где в статье про это написано?
Затруднялся с написанием документации для проекта. Теперь есть хорошее руководство — спасибо.
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Создание документации в .NET