10 ноября 2010 г.

Документация в исходном коде - раунд 2

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

Сегодня, я вернусь к этому вопросу с новой информацией.

Итак, напомню, что речь идёт о внедрении документации в код. При этом справка оформляется в виде специальных комментариев вроде (стиль JavaDoc):
{*------------------------------------------------------------------------------
  Конвертирует дату-время из отчёта в TDateTime.
 
  @param  AValue Строка, представляющая дату из отчёта. Имеет формат вида 'Sun, 25 Jan 2009 12:48:15 +0300'.
  @return Значение TDateTime (по местному времени), которое соответствует параметру AValue, или 0, если AValue не содержит корректного представления даты.
  @throws нет
  @see    GetDate
-------------------------------------------------------------------------------}
function GetDateTime(const AValue: String): TDateTime;
begin
  ...
end;
или (стиль XML-Doc):
/// <summary>Конвертирует дату-время из отчёта в TDateTime.</summary>
/// <param name="AValue">Строка, представляющая дату из отчёта. Имеет формат вида 'Sun, 25 Jan 2009 12:48:15 +0300'.<param>
/// <returns>Значение TDateTime (по местному времени), которое соответствует параметру AValue, или 0, если AValue не содержит корректного представления даты.</returns>
/// <seealso cref="GetDate">GetDate</seealso>
function GetDateTime(const AValue: String): TDateTime;
begin
  ...
end;
Плюсы и минусы документации в коде:
  • (+) Всегда актуальная документация. Вы можете изменить функцию (убрать/добавить) и забыть обновить документацию, ведомую вручную. Но вы не можете забыть сделать это для документации, которая пишется вместе с кодом.
  • (+) Очень просто писать - нужно просто добавить специально оформленный комментарий (который, кстати, может быть забит в шаблон Code Template).
  • (-) Нет GUI. GUI удобно, когда ты не помнишь наизусть все эти правила и тэги.
  • (-) Нет WYSIWYG.
  • (-) Автоматическая генерация справки может уступать по "красоте" ручной.
  • (-) Сильно засоряет код. Большие блоки комментариев могут затруднять чтение кода.
Первый пункт - это достаточно сильный плюс, на который приходится больше мелких минусов.

До сегодняшнего дня я считал, что документация в коде - это достаточно спорный момент. Но сегодня я узнал об одной утилите, которая изменила моё мнение в сторону полной поддержки документации в коде.

Встречаем: Documentation Insight - add-in для Delphi IDE, реализующий WYSIWYG-редактор для редактирования документации в исходном коде.

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

Требования:
  • Internet Explorer 7 или выше
  • MSXML 6.0
Поддерживаемые среды:
  • RAD Studio 2007
  • RAD Studio 2010
  • RAD Studio XE
Плагин устанавливается установщиком. После установки он появляется в меню Tools или может быть вызван по Ctrl + Shift + D (комбинация меняется):


Появится окно, которое можно пристыковать или использовать как плавающее - равно как все остальные окна IDE:


Что же такого позволяет делать это расширение?

Ну, как вы уже увидели на снимках экрана, оно предоставляет вам GUI-интерфейс для редактирования документации в комментариях. Кроме того, оно автоматически расставляет тэги свёртки кода (code folding) для больших текстов. Вот как выглядит документация в коде (слева - свёрнуто, справа - развёрнуто):


Таким образом, документация не засоряет код и совершенно не мешается. Справедливости ради надо сказать, что Code Folding - фишка IDE, а не плагина. Но то, что он её использует - большое удобство.

Использование плагина тривиально - вы щёлкаете на функцию, метод, тип или переменную в коде - она отображается в окне Documentation Insight в том виде, как она получилась бы в документации. По-умолчанию никакого описания у объектов нет - только малоинформативный авто-шаблон.

Чтобы отредактировать описание объекта, вы можете делать это по старинке: вписывая специальным образом оформленные комментарии в код, либо же используя Documentation Insight. Для последнего случая вам нужно переключить его из режима просмотра в режим редактирования. Делается это самой правой кнопкой со значком листа и ручки. Слева - режим просмотра. Справа - режим редактирования:


В режиме редактирования вы можете щёлкать по блокам текста и вводить описания. Панель инструментов сверху даёт вам доступ к WYSIWYG-оформлению. Для списочных значений (например, блока Exceptions) ввод строки автоматически расширяет список, вводя новую пустую строку в конец списка.

Инструмент поддерживает множество тэгов и даёт возможность вставлять их в текст. Вот пример возможностей:


Ещё одна очень клёвая фишка этого расширения - интеграция со справкой Delphi. Например, вы переходите к объявлению метода IndexOf класса TStringList, либо же находитесь внутри его - и Documentation Insight покажет вам документацию по этому методу:


Здорово, да? Понятно, что редактировать это описание вы не сможете, но зато вы получаете цельное представление, как о своём коде, так и о коде Delphi - в однообразном виде, что очень приятно. Кстати, все ссылки в окне Documentation Insight - рабочие.

В заключение хотелось бы отметить, что расширение пока поддерживает только документацию в стиле XML-doc. Кроме того, надо сказать, что документация в стиле XML-doc подхватывается ещё и самой Delphi для использования в Help Insight! Например, вот как выглядит всплывающая подсказка в IDE Delphi для функции с документацией:


Чрезвычайно приятно видеть, как несколько разрознённых возможностей так удачно работают вместе (эй, это не так уж часто бывает в Delphi!).

Примечание: Help Insight обрабатывает не все допустимые тэги, но вы можете самостоятельно изменить шаблон (или взять готовый), если вы что-то понимаете в XSL-преобразованиях.

Ах да, упомянул ли я, что этот прекрасный инструмент совершенно бесплатен? :)

Обновление: автор Documentation Insight (Baoquan Zuo) указал, что они хотят развивать Documentation Insight и поэтому он будет платным продуктом. Бета версии бесплатны, но имеют ограничения на время работы.

Итак, давайте подведём итоги. Вот плюсы и минусы документации в коде с использованием Documentation Insight и новых Delphi:
  • (+) Всегда актуальная документация.
  • (+) Очень просто писать.
  • (+) На выбор есть GUI или старомодный способ ручного написания комментариев.
  • (+) WYSIWYG.
  • (+) Практически не засоряет код. Вы также можете настроить поведение свёртки блоков.
  • (+) Интеграция с Code Insight.
  • (-) Автоматическая генерация справки может уступать по "красоте" ручной.
Я думаю, что с таким перевесом плюсов выбор очевиден: ведите документацию в коде!

Обновление: Documentation Insight является частью Delphi, начиная с Delphi XE 2.

25 комментариев :

  1. К сожалению, в лагере генераторов документации всё не так радужно. Мой любимый Help & Manual не поддерживает генерацию документации по коду, ибо его основное предназначение - пользовательская справка.

    Нормальным выбором видится Doc-O-Matic, но его минимальная цена (за Doc-O-Matic SRC) - $500 :(

    ОтветитьУдалить
  2. Ещё надо заметить, что базовая поддержка генерации справки по коду есть и в самой Delphi: включите поддержку Modelling (в меню: View/Model View), в опциях проекта включите опцию "Generate XML Documentation" (вкладка "Compiling").

    Теперь можно щёлкнуть правой кнопкой мыши по проекту в окне Model View и выбрать команду "Generate documentation".

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

    Вы можете его настроить - используя правку XSL-шаблонов, но CHM, PDF или MS Help вы из этого не извлечёте.

    Да, и, вроде бы, эта функция есть не во всех редакциях Delphi.

    ОтветитьУдалить
  3. Сильная штука. Спасибо за статью!

    ОтветитьУдалить
  4. И ты кардианльно сменил свою точку зрения?
    Не уж то будешь абсолютно все функции покрывать документацией? или предел есть?

    ОтветитьУдалить
  5. Yep, я поменял. Осталось подобрать инструмент для конвертации доков в комментах в хэлп-файл и начну делать.

    А предел... да ровно такой же, каков предел покрытия документации в справке, составляемой вручную. Ну, может и шире. В идеале - надо бы описать каждую функцию, класс, метод, тип. На практике - как получится. Понятно, что совсем очевидные можно отложить на потом.

    В Doc-O-Matic самой продвинутой редакции есть полезный инструмент, позволяющий графически показать степень покрытия кода документацией.

    ОтветитьУдалить
  6. Графически? Это он код графически представляет или раскрашивает исходник?

    ОтветитьУдалить
  7. Тут на вкладке Screenshot два скрина с красно-зелёной диаграммой. При щелчке на кубике показывается, что это за объект.

    Красный - документации нет.
    Зелёный - документация есть.

    ОтветитьУдалить
  8. P.S. Описывать максимум функций (по возможности) полезно ещё и тем, что вся эта информация показывается сразу же в IDE - через Help Insight.

    ОтветитьУдалить
  9. Спасибо за прекрасный способ генерации доков!!!!!!!

    ОтветитьУдалить
  10. А софтина то не бесплатная :(
    И еще с первой беты бесплатной не была

    ОтветитьУдалить
  11. Доброго времени суток!

    Почему у меня вот так: http://funkyimg.com/u2/360/761/DocInsight_abracadabra.jpg

    Delphi 2010 v14.0.3593 Win7 x64 Ultimate

    ОтветитьУдалить
  12. А почему вы меня об этом спрашиваете?

    ОтветитьУдалить
  13. Потому что это стало после установке вашего шаблона для ХелпИнсайт, возвращаю штатный шаблон - абракадабра исчезает :).

    ОтветитьУдалить
  14. Вы чего-то путаете. Я в жизни не делал ни одного шаблона для HelpInsight и ничего в этом не понимаю.

    Наверное, вы имели ввиду этот шаблон. Ну так и пишите автору этого шаблона.

    ОтветитьУдалить
  15. А почему же


    Credits
    GunSmoker
    Marco Cantu

    :)

    ОтветитьУдалить
  16. Credits = участники, сделали вклад.

    Я тестировал этот шаблон по просьбе автора (Baoquan Zuo). Думаю, что Marco Cantu помог ему с информацией о шаблонах.

    ОтветитьУдалить
  17. А у вас кириллица работает?

    ОтветитьУдалить
  18. Да, нормально работает.

    Судя по скрину, у вас могли не подключиться все файлы - как-то странно он выглядит, как будто стили не подключены.

    ОтветитьУдалить
  19. Несколько раз всё перепроверил, старый шаблон возвращаю - нормально, новый - крякозябры. Неужели где-то надо поставить Cyrillic в шаблоне, проглядел все файлы - ничего подходящего не нашёл :(. К сожалению в CSS / XSL не знаток.

    ОтветитьУдалить
  20. Так там не кириллица, а UTF-8.

    Сейчас посмотрел: если ты не копируешь папку, а только один файл, то как раз и получается ситуация, как на скриншоте. Потому что шаблон не может загрузить файлы из папки.

    Инструкция была: "You should backup your local HelpInsight.xsl file and then extract the downloaded zip file to the corresponding location".

    Т.е. должно быть:
    - До: HelpInsight.xsl
    - После: HelpInsight.xsl, HelpInsight_backup.xsl, HelpInsight (папка).

    ОтветитьУдалить
  21. Скопировал всё как в инструкции, всё равно вот так. Счас попробую ИДЕ перегрузить.

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

    А уж почему это происходит - надо разбираться.

    Проверить права на папку. Проверить, что не перепутано {$BDS}\ObjRepos\en и {$BDS}\ObjRepos (в D2010 {$BDS}\ObjRepos не будет работать).

    ОтветитьУдалить
  23. Вот скрин папки:

    http://funkyimg.com/u2/747/786/DocInsight_1.jpg

    ОтветитьУдалить
  24. Ну я не знаю. Должно работать. У меня работает именно в таком раскладе. Я как поставил тогда, так и не удалял, всегда сижу с этим шаблоном.

    Могу только посоветовать обратиться к автору шаблона. Он в этом хотя бы понимает.

    Я - нет.

    ОтветитьУдалить
  25. Анонимный28 июля 2011 г., 11:17

    а для Lazarus подобного нет?

    ОтветитьУдалить

Можно использовать некоторые HTML-теги, например:

<b>Жирный</b>
<i>Курсив</i>
<a href="http://www.example.com/">Ссылка</a>

Вам необязательно регистрироваться для комментирования - для этого просто выберите из списка "Анонимный" (для анонимного комментария) или "Имя/URL" (для указания вашего имени и (опционально) ссылки на сайт). Все прочие варианты потребуют от вас входа в вашу учётку (поддерживается OpenID).

Пожалуйста, по возможности используйте "Имя/URL" вместо "Анонимный". URL можно просто не указывать.

Ваше сообщение может быть помечено как спам спам-фильтром - не волнуйтесь, оно появится после проверки администратором.