Практическая автоматизация: Создание документации одним нажатием кнопки

Автоматизируйте процесс создания документации для пользователей и разработчиков вашего продукта

Написание проектной документации зачастую является одним из наиболее трудоемких, но необходимых этапов создания программного продукта. Представьте себе, что эту задачу можно выполнить одним нажатием на кнопку! В этой статье серии Практическая автоматизация эксперт по вопросам автоматизации Пол Дюваль расскажет об использовании открытых средств для генерации диаграмм UML (Unified Modeling Language), схем сборки проекта, диаграмм типа "сущность-связь" (ERD) и даже документации для конечных пользователей.

Пол Дюваль, технический директор, Stelligent Incorporated

Paul DuvallПол Дюваль (Paul Duvall) является техническим директором компании Stelligent Incorporated – консалтинговой фирмы, которая помогает командам разработчиков оптимизировать гибкие методологии разработки программного обеспечения. Он также соавтор книги Continuous Integration: Improving Software Quality and Reducing Risk (Addison-Wesley, 2007 г.). Он принимал участие в создании книг UML 2 Toolkit (Wiley, 2003 г.) и No Fluff Just Stuff Anthology (Pragmatic Programmers, 2007 г.).



14.07.2010

Мне нечасто встречаются разработчики, которые бы утверждали, что получают удовольствие от процесса написания программной документации. Тем не менее очень важно документировать ваши приложения в понятной для других форме, если, конечно, вы не намерены вечно работать над вашим продуктом в качестве единственного разработчика (либо у вашего продукта нет пользователей, что, как правило, не является положительным признаком). Некоторые разработчики превратно понимают лозунг методологии гибкой разработки приложений (agile development, см. раздел Ресурсы), который звучит как "Working software over comprehensive documentation" ("правильность работы приложения важнее полноты документации"). Это отнюдь не означает, что документация не нужна вообще. С другой стороны, не следует обременять пользователей или других разработчиков чтением документации, которая не нужна для работы с приложением. Лучше всего найти золотую середину. Как вы, наверное, уже догадались, далее речь пойдет об автоматизации процесса написания документации, в частности о том, как она позволяет снизить нагрузку на разработчиков.

Об этой серии

Будучи разработчиками, мы автоматизируем процессы для конечных пользователей; однако многие из нас не замечают возможности автоматизировать наш собственный процесс разработки. Для этого предназначена серия статей Практическая автоматизация, в которой исследуются практические аспекты автоматизации процессов разработки программ и обучения тому, когда и как успешно применять автоматизацию.

Мой опыт говорит о том, что написание документации к программному продукту связано с двумя основными проблемами. Во-первых, существует высокая вероятность, что ее никто не будет читать. Во-вторых, документация устаревает практически сразу после написания. Эти проблемы взаимосвязаны, в частности, если бы документация поддерживалась в актуальном состоянии, то ее бы охотнее читали. Одним из способов этого является автоматизация процесса создания документации, что делает ее значительно полезнее для пользователей.

Скорее всего, можно автоматизировать процессы создания разных видов документации, однако в данной статье мы рассмотрим автоматизацию только тех задач, которые являются наиболее проблемными, исходя из моего опыта (ссылки на упоминаемые ниже приложения можно найти в разделе Ресурсы):

  • генерация UML-диаграмм по исходному коду (с использованием UMLGraph);
  • создание диаграмм типа "сущность-связь" (ERD) для описания таблиц базы данных и связей между ними (при помощи SchemaSpy);
  • создание диаграмм сборки проекта, описывающих задания Ant и связи между ними (с использованием Grand);
  • генерация документации непосредственно из исходного кода с использованием Doxygen;
  • создание пользовательской документации при помощи DocBook.

Подход к каждой задаче будет описываться в следующем едином формате:

  1. описание проблем, связанных с ручным выполнением задачи;
  2. описание примера автоматизации при помощи Apache Ant в сочетании с соответствующим средством генерирования документации и/или диаграмм;
  3. демонстрация фрагмента документации, сгенерированного по исходному коду примеров.

Как уже принято в этой серии, во всех примерах используется только бесплатное программное обеспечение, которое вы можете применять в своих проектах. Некоторые из приложений, в частности UMLGraph и Grand, используют библиотеку GraphViz, передавая ей на вход сгенерированные файлы с расширением .dot.

Анализ кода и построение UML-диаграмм

В моей практике встречались проекты, UML-диаграммы в которых были выполнены настолько хорошо, насколько это вообще можно себе представить. К сожалению, они были созданы в начале проекта, поэтому проблемы заключались в том, что в одном случае технический руководитель проекта просто не поддерживал их в актуальном по отношению к исходному коду состоянии, а в другом – тратил много времени, вручную обновляя диаграммы по коду проекта (этот процесс еще называют реверс-инжинирингом). Разумеется, ни один из этих вариантов не является оптимальным. Любая, даже идеально построенная, UML-диаграмма оказывается бесполезной, если описываемая ею модель не соответствует коду в репозитории. Какие бы решения вы ни принимали, если они не основаны на актуальном состоянии исходного кода, то, скорее всего, приведут к проблемам в будущем.

Можно значительно повысить значение диаграмм для процесса принятия решений, а также упростить их создание и обновление, включив процедуру их генерации в процесс сборки проекта. Также имеет смысл настроить среду непрерывной интеграции (Continuous Integration – CI), указав, что диаграммы необходимо перестраивать либо при каждом изменении исходного кода, либо с заданной периодичностью.

В листинге 1 показан фрагмент файла сборки Ant, генерирующий документацию по исходному коду при помощи UMLGraph и GraphViz.

Листинг 1. Пример использования UMLGraph в Ant
<property name="reports.dir" value="${basedir}/reports"/>
  <mkdir dir="${reports.dir}"/>
  <path id="project.path">
    <pathelement path="${basedir}/src"/>
    <pathelement path="${basedir}/lib"/>
  </path>
  <javadoc sourcepath="${basedir}/src" destdir="${reports.dir}" 
    classpathref="project.path" access="private">
    <doclet name="org.umlgraph.doclet.UmlGraphDoc" 
    path="UMLGraph.jar">
        <param name="-attributes" />
        <param name="-enumerations" />
        <param name="-enumconstants" />
        <param name="-operations" />
        <param name="-qualify" />
        <param name="-types" />
        <param name="-visibility" />
    </doclet>
  </javadoc>
  <apply executable="dot" dest="${reports.dir}" parallel="false">
    <arg value="-Tpng"/>
    <arg value="-o"/>
     <targetfile/>
     <srcfile/>
     <fileset dir="${reports.dir}" includes="*.dot"/>
     <mapper type="glob" from="*.dot" to="*.png"/>
  </apply>

В этом примере UMLGraph используется в сочетании с Javadoc для генерации базовых диаграмм классов и вставки их в HTML-страницы Javadoc. Для конфигурирования информации, которая будет отображаться на каждой диаграмме классов, используются следующие атрибуты задания UmlGraphDoc:

Построение графиков при помощи GraphViz

Для работы UMLGraph необходимо, чтобы на вашем компьютере была установлена программа GraphViz (см. раздел Ресурсы). Кроме того, файл .dot для GraphViz должен находиться в одном из системных каталогов.

  • -attributes: отображение полей класса;
  • -enumerations: отображение различных перечислений;
  • -enumconstants: отображение списка значений перечисления;
  • -operations: отображение методов класса;
  • -qualify: отображение полностью квалифицированных имен классов;
  • -types: отображение типов параметров и возвращаемого значения методов;
  • -visibility: отображение модификаторов доступа для полей и методов (public, protected, private или default).

На рисунке 1 показан пример UML-диаграммы, на которой представлен класс LoginDaoImpl и его связи с другими классами. Диаграмма была сгенерирована и вставлена в HTML-страницу при помощи UMLGraph.

Рисунок 1. Пример UML-диаграммы, созданной при помощи UMLGraph
UML diagram of Java class and its relationships generated by UMLGraph

Для просмотра полномасштабной версии диаграммы нажмите здесь.

При помощи UMLGraph можно генерировать диаграммы, отображающие дополнительную информацию, в частности, более сложные связи между классами. Однако даже простые диаграммы классов весьма информативны. Они позволяют быстро получить визуальное представление о приложении на основе текущей версии исходного кода. Благодаря им, разработчикам не приходится придумывать объяснения наподобие такого: "данный модуль задумывался таким-то образом". Кроме того, на основе диаграмм легче принимать решения, относительно того или иного фрагмента кода. Ссылка на источник дополнительной информации об атрибутах, при помощи которых можно настраивать вывод UMLGraph, приведена в разделе Ресурсы.


Документирование баз данных

Автоматическая визуализация базы данных не менее важна, чем генерация UML-диаграмм, описывающих классы приложения. Наиболее популярным типом визуального представления баз данных являются ER-диаграммы (или диаграммы типа "сущность–связь"). Большинство приложений для создания ER-диаграмм (в том числе ERWin) требуют ручного описания сущностей и связей. Мы же рассмотрим программу под названием SchemaSpy, которая хотя и уступает по функциональности более сложным продуктам, но зато способна генерировать высокоуровневое представление базы данных вместе со всеми ограничениями, связями и т.д. Более того, вызов SchemaSpy можно включить в процесс сборки приложения, таким образом генерируя визуальное представление текущей версии кода, описывающего объекты базы данных (этот код представляет собой набор операторов на языке определения данных – Data Definition Language или DDL).

В листинге 2 приведен скрипт сборки Ant, вызывающий SchemaSpy для генерации файла, отформатированного для использования в Javadoc.

Листинг 2. Использование SchemaSpy в сочетании с Ant и Javadoc
<property name="reports.dir" value="${basedir}"/>
<java jar="schemaSpy_3.1.1.jar"
  output="${reports.dir}/output.log"
  error="${reports.dir}/error.log"
  fork="true">
  <arg line="-t mysql"/>
  <arg line="-host localhost"/>
  <arg line="-port 3306"/>
  <arg line="-db brewery"/>
  <arg line="-u root"/>
  <arg line="-p sa"/>
  <arg line="-cp mysql-connector-java-5.0.5-bin.jar"/>
  <arg line="-o ${reports.dir}"/>
</java>

Скрипт, показанный в листинге 2, передает SchemaSpy следующий набор параметров:

  • -t: тип базы данных. Он может принимать значения mysql, ora, db2 и т.д.;
  • -host: имя компьютера, на котором размещена база данных;
  • -port: номер порта в URL базы данных;
  • -u: имя пользователя для соединения с базой данных;
  • -p: пароль;
  • -cp: classpath Java-приложения (в данном примере этот параметр используется для задания пути к JAR-файлу, включающему драйвер базы данных);
  • -o: местоположение сгенерированного файла.

SchemaSpy, вызванный с данными параметрами, генерирует ER-диаграмму в виде HTML (рисунок 2).

Рисунок 2. ER-диаграмма, созданная при помощи SchemaSpy и Ant
ERD created with SchemaSpy and Ant

Сочетая использование нескольких программ для генерации ER-диаграмм как в процессе сборки проекта, так и в соответствии с заранее определенным планом, вы можете существенно облегчить принятие решений, касающихся базы данных, на этапе разработки приложения.


Создание диаграмм, описывающих процесс сборки проекта

Нередко скрипты для сборки проекта включают в себя сложные связи между несколькими взаимозависимыми целями (target). Мне приходилось видеть скрипты, содержащие более 1000 строк кода, в том числе дублирующиеся фрагменты. В подобных скриптах бывает тяжело разобраться, не имея перед глазами общей визуальной картины процесса сборки. Одним из эффективных способов быстрого определения того, что происходит (или не происходит) в процессе выполнения данного скрипта, является создание диаграммы, описывающей сами цели сборки и связи между ними. Визуальное представление целей скрипта Ant может быть полезным для принятия эффективных и рациональных решений по улучшению дизайна автоматической сборки проекта.

Точную визуальную модель целей сборки можно создать при помощи Ant, Grand и GraphViz. Существует множество программ, позволяющих визуализировать цели Ant, однако преимуществом Grand является то, что он использует API самого Ant, поэтому он способен строить диаграммы вне зависимости от возможности запуска Ant-скрипта.

В листинге 3 приведен пример Ant-скрипта, использующего Ant для создания визуального представления целей Ant и связей между ними.

Листинг 3. Пример создания диаграмм вызова целей Ant при помощи Ant и Grand
<target name="create-ant-diagram">
  <property name="file.type" value="pdf" />
  <typedef resource="net/ggtools/grand/antlib.xml" 
    classpath="grand-1.8.jar"/>
  <grand output="build.dot" buildfile="${basedir}/build.xml"/>
    <exec executable="dot" >
      <arg line="-T${file.type} -Gsize=11.69,8.27 -Grotate=90 -o build.${file.type} 
    ${grand.output.file}"/>
    </exec>
</target>

В начале листинга 3 определяется новое задание, реализация которого находится в файле grand-1.8.jar. Далее вызывается Grand, получая на вход имя анализируемого скрипта через атрибут buildfile. В атрибуте output задается имя файла для GraphViz, генерируемого Grand (build.dot). Наконец, происходит вызов утилиты dot, входящей в состав GraphViz, которая генерирует диаграмму целей в виде PDF. Внешний вид диаграммы показан на рисунке 3.

Рисунок 3. Диаграмма вызовов целей Ant, созданная при помощи Ant, Grand и GraphViz
Diagram of Ant targets generated by Ant, Grand, and GraphViz

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


Документирование кода

Я пишу комментарии к своему коду в случаях, когда мне важно запомнить, почему я создал тот или иной Java-класс или метод. Однако если требуется более полное описание классов, методов и атрибутов, то необходимо некоторое средство для автоматизированной генерации документации. Исторически в состав платформы Java для этой цели входит утилита Javadoc, которая генерирует документацию по всем классам проекта. Более того, Ant включает в себя стандартное задание javadoc, создающее документацию. Однако разработчикам приходится самостоятельно вставлять неприглядную HTML-разметку в комментарии к Java-классам. В листинге 4 приведен пример комментариев с HTML-тегами, вставленными в расчете на использование Javadoc.

Листинг 4. Комментарии для Javadoc в коде приложения
/**
  This is <i>the</i> LoginServiceImpl  class.  
  <p> 
  Refer to <a href="url.html">
  LoginService overview</a> for more details.
  <p>
  There is one type of supported {@link LoginServiceImpl }:
  <ul>
    <li>{@link LoginServiceImpl } (this class)</li>
  </ul>
*/

При помощи Doxygen можно сократить объем комментариев, избавившись от вложенных тегов HTML. Пример показан в листинге 5.

Листинг 5. Комментарии для Doxygen в исходном коде
/**
This is <i>the</i> LoginServiceImpl class.
Refer to \ref LoginService for more details.
There is one type of supported LoginService:
- LoginServiceImpl (this class)
*/

И Javadoc, и Doxygen способны автоматически генерировать документацию по исходному коду, однако Doxygen облегчает задачу разработчика, предлагая более интуитивно понятный подход к аннотированию кода при помощи комментариев. Базовый пример вызова Doxygen из скрипта Ant приведен в листинге 6.

Листинг 6. Скрипт Ant, вызывающий Doxygen
<target name="generate-doxygen">
  <taskdef name="doxygen" classname="org.doxygen.tools.DoxygenTask" 
    classpath="ant-doxygen.jar" />
  <doxygen configFilename="Doxyfile">
  <property name="INPUT" value="${src.dir}" />
  <property name="RECURSIVE" value="yes" />
  </doxygen>
</target>

Атрибут configFilename со значением Doxyfile задает имя конфигурационного файла, сгенерированного при помощи Doxygen. Вы можете изменить его, приспособив под свои задачи. На рисунке 4 показан пример отчета в формате HTML, который был автоматически создан при помощи скрипта из листинга 6 для класса LoginDaoImpl.

Рисунок 4. Документация в формате HTML, созданная при помощи Doxygen
HTML Doxygen documentation

Для просмотра полномасштабной версии диаграммы нажмите здесь.

Использование Doxygen в процессе автоматизированной сборки проекта позволяет генерировать наиболее актуальную документацию по разрабатываемому API.


Создание документации для пользователей

Вам могло показаться, что, несмотря на все свои преимущества, автоматическая генерация технической документации не решит ваших проблем, которые заключаются в создании документации для пользователей. У меня есть опыт написания пользовательской документации, причем немалую часть времени мне приходилось тратить на копирование и вставку одной и той же информации. Проанализировав этот процесс, я пришел к выводу, что можно автоматизировать вставку такой информации, как, например, номера версий или имена файлов, которые можно определить в отдельном месте. Далее можно отделить содержание документации от ее представления путем использования таких технологий, как XML и XSL (расширяемый язык стилей). Таким образом можно радикально изменять внешний вид документов, лишь модифицируя таблицу стилей.

С давних времен известна программа DocBook, которая позволяет описывать документы в XML, а затем конвертировать их в различные форматы, в том числе HTML и PDF. DocBook также предоставляет схему, определяющую набор шаблонов для использования техническими писателями.

В листинге 7 приведен пример использования Ant, XSL-страницы из поставки DocBook, а также форматирующих объектов XSL (XSL-FO) для генерации пользовательской документации в формате PDF (см. раздел Ресурсы).

Листинг 7. Создание документов PDF при помощи Ant, DocBook и FO
<target name="pdf" depends="init" description="Generates PDF files from DocBook XML">
  <property name="fo.stylesheet" value="${docbook.xsl.dir}/fo/docbook.xsl" />
  <xslt style="${fo.stylesheet}" extension=".fo" basedir="${src.dir}" destdir="${fo.dir}">
    <classpath refid="xalan.classpath" />
    <include name="${guide}.xml" />
  </xslt>
  <property name="fop.home" value="lib/fop-0.94" />
  <taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop">
    <classpath>
      <fileset dir="${fop.home}/lib">
        <include name="*.jar" />
      </fileset>
      <fileset dir="${fop.home}/build">
        <include name="fop.jar" />
        <include name="fop-hyph.jar" />
      </fileset>
    </classpath>
  </taskdef>
  <fop format="application/pdf" fofile="${fo.dir}/${guide}.fo" 
    outfile="${doc.dir}/${guide}.pdf" />
</target>

Секция PDF-документа, созданного скриптом, приведенным в листинге 7, показана на рисунке 5.

Рисунок 5. Фрагмент пользовательской документации в формате PDF
PDF of user-guide documentation

Поскольку все содержимое представлено в виде XML, можно легко создавать скрипты, способные изменять документацию гибким образом. Более того, документы можно создавать в процессе сборки проекта. Таким образом, этот процесс будет выступать единственным источником таких данных, как номера версий, аббревиатуры, различные определения, имена файлов и каталогов.


Документацию необязательно создавать вручную

Я надеюсь, что прочитав эту статью, вы убедились, что существуют эффективные подходы к автоматическому созданию документации. На мой взгляд, самое важное в документации – это обмен информацией, а не процесс генерации документов. При помощи средств и способов автоматизации, описанных в этой статье, вы сможете поддерживать свою документацию в точном и актуальном состоянии. Это поможет вам решить проблему устаревания информации – главную причину недостаточного использования документации.

Ресурсы

Научиться

Получить продукты и технологии

  • Ant: загрузите Ant и начните собирать ваши приложения надежным и предсказуемым способом. (EN)
  • Grand: загрузите Grand и создавайте диаграммы, описывающие скрипты Ant. (EN)
  • SchemaSpy: загрузите SchemaSpy, который позволяет создавать ER-диаграммы, описывающие схемы баз данных. (EN)
  • Doxygen: загрузите Doxygen, который позволяет генерировать подробную документацию по исходному коду. (EN)
  • UMLGraph: загрузите UMLGraph, который предоставляет возможность автоматического создания UML-диаграмм из исходного кода. (EN)
  • DocBook: загрузите DocBook и генерируйте документацию в различных форматах. (EN)

Обсудить

Комментарии

developerWorks: Войти

Обязательные поля отмечены звездочкой (*).


Нужен IBM ID?
Забыли Ваш IBM ID?


Забыли Ваш пароль?
Изменить пароль

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Профиль создается, когда вы первый раз заходите в developerWorks. Информация в вашем профиле (имя, страна / регион, название компании) отображается для всех пользователей и будет сопровождать любой опубликованный вами контент пока вы специально не укажите скрыть название вашей компании. Вы можете обновить ваш IBM аккаунт в любое время.

Вся введенная информация защищена.

Выберите имя, которое будет отображаться на экране



При первом входе в developerWorks для Вас будет создан профиль и Вам нужно будет выбрать Отображаемое имя. Оно будет выводиться рядом с контентом, опубликованным Вами в developerWorks.

Отображаемое имя должно иметь длину от 3 символов до 31 символа. Ваше Имя в системе должно быть уникальным. В качестве имени по соображениям приватности нельзя использовать контактный e-mail.

Обязательные поля отмечены звездочкой (*).

(Отображаемое имя должно иметь длину от 3 символов до 31 символа.)

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Вся введенная информация защищена.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=Технология Java, Open source
ArticleID=500427
ArticleTitle=Практическая автоматизация: Создание документации одним нажатием кнопки
publish-date=07142010