Документация в исходном коде - раунд 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.