1. Серія контенту:
2. Цей контент є частиною серії: Практична автоматизація
3. Про цю серії
4. Аналіз коду та побудова UML-діаграм
5. Лістинг 1. Приклад використання UMLGraph в Ant
6. Побудова графіків за допомогою GraphViz
7. Малюнок 1. Приклад UML-діаграми, створеної за допомогою UMLGraph
8. Документування баз даних
9. Лістинг 2. Використання SchemaSpy в поєднанні з Ant і Javadoc
10. Малюнок 2. ER-діаграма, створена за допомогою SchemaSpy і Ant
11. Створення діаграм, що описують процес складання проекту
12. Лістинг 3. Приклад створення діаграм виклику цілей Ant за допомогою Ant і Grand
13. Малюнок 3. Діаграма викликів цілей Ant, створена за допомогою Ant, Grand і GraphViz
14. документування коду
15. Лістинг 4. Коментарі для Javadoc в коді програми
16. Лістинг 5. Коментарі для Doxygen в вихідному коді
17. Лістинг 6. Скрипт Ant, що викликає Doxygen
18. Малюнок 4. Документація в форматі HTML, створена за допомогою Doxygen
19. Створення документації для користувачів
20. Лістинг 7. Створення документів PDF за допомогою Ant, DocBook і FO
21. Малюнок 5. Фрагмент користувальницької документації в форматі PDF
22. Документацію необов'язково створювати вручну
23. Ресурси для скачування

практична автоматизація

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

Серія контенту:

Цей контент є частиною # з серії # статей: Практична автоматизація

https://www.ibm.com/developerworks/ru/views/global/libraryview.jsp?series_title_by=Практическая+автоматизация

Слідкуйте за виходом нових статей цієї серії.

Цей контент є частиною серії: Практична автоматизація

Слідкуйте за виходом нових статей цієї серії.

Мені нечасто зустрічаються розробники, які б стверджували, що отримують задоволення від процесу написання програмної документації. Проте дуже важливо документувати ваші програми в зрозумілій для інших формі, якщо, звичайно, ви не маєте наміру вічно працювати над вашим продуктом в якості єдиного розробника (або у вашого продукту немає користувачів, що, як правило, не є позитивною ознакою). Деякі розробники перекручено розуміють гасло методології гнучкої розробки додатків (agile development, див. ресурси ), Який звучить як "Working software over comprehensive documentation" ( "правильність роботи програми важливіше повноти документації"). Це аж ніяк не означає, що документація не потрібна взагалі. З іншого боку, не слід обтяжувати користувачів або інших розробників читанням документації, яка не потрібна для роботи з додатком. Найкраще знайти золоту середину. Як ви, напевно, вже здогадалися, далі мова піде про автоматизацію процесу написання документації, зокрема про те, як вона дозволяє знизити навантаження на розробників.

Про цю серії

Будучи розробниками, ми автоматизуємо процеси для кінцевих користувачів; проте багато з нас не помічають можливості автоматизувати наш власний процес розробки. Для цього призначена серія статей jsp?search_by=automation+people:> практична автоматизація , В якій досліджуються практичні аспекти автоматизації процесів розробки програм і навчання тому, коли і як успішно застосовувати автоматизацію.

Мій досвід говорить про те, що написання документації до програмного продукту пов'язане з двома основними проблемами. По-перше, існує висока ймовірність, що її ніхто не читатиме. По-друге, документація застаріває практично відразу після написання. Ці проблеми взаємопов'язані, зокрема, якби документація підтримувалася в актуальному стані, то її б охочіше читали. Одним із способів цього є автоматизація процесу створення документації, що робить її значно корисніше для користувачів.

Швидше за все, можна автоматизувати процеси створення різних видів документації, проте в даній статті ми розглянемо автоматизацію тільки тих завдань, які є найбільш проблемними, виходячи з мого досвіду (посилання на згадувані нижче додатки можна знайти в розділі ресурси ):

• генерація 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

У цьому прикладі 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

Для перегляду повномасштабної версії діаграми натисніть тут .

За допомогою UMLGraph можна генерувати діаграми, що відображають додаткову інформацію, зокрема, більш складні зв'язки між класами. Однак навіть прості діаграми класів досить інформативні. Вони дозволяють швидко отримати візуальне уявлення про програму на основі поточної версії вихідного коду. Завдяки їм, розробникам не доводиться придумувати пояснення на кшталт такого: "даний модуль замислювався таким-то чином". Крім того, на основі діаграм легше приймати рішення, щодо того чи іншого фрагмента коду. Посилання на джерело додаткової інформації про атрибути, за допомогою яких можна налаштувати показ UMLGraph, наведена в розділі ресурси .

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

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

У лістингу 2 наведено скрипт збірки Ant, що викликає SchemaSpy для генерації файлу, відформатованого для використання в Javadoc.

Лістинг 2. Використання SchemaSpy в поєднанні з Ant і Javadoc

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

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

SchemaSpy, викликаний з даними параметрами, генерує ER-діаграму у вигляді HTML (малюнок 2).

Малюнок 2. ER-діаграма, створена за допомогою SchemaSpy і Ant

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

Створення діаграм, що описують процес складання проекту

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

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

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

Лістинг 3. Приклад створення діаграм виклику цілей Ant за допомогою Ant і Grand

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

Малюнок 3. Діаграма викликів цілей Ant, створена за допомогою Ant, Grand і GraphViz

Подібні діаграми можна використовувати для аналізу закінченого проекту або з метою вдосконалення процесу складання поточного проекту.

документування коду

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

Лістинг 4. Коментарі для Javadoc в коді програми

За допомогою Doxygen можна скоротити обсяг коментарів, позбувшись від вкладених тегів HTML. Приклад показаний в лістингу 5.

Лістинг 5. Коментарі для Doxygen в вихідному коді

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

Лістинг 6. Скрипт Ant, що викликає Doxygen

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

Малюнок 4. Документація в форматі HTML, створена за допомогою Doxygen

Для перегляду повномасштабної версії діаграми натисніть тут .

Використання Doxygen в процесі автоматизованого складання проекту дозволяє генерувати найбільш актуальну документацію щодо розроблюваного API.

Створення документації для користувачів

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

З давніх часів відома програма DocBook, яка дозволяє описувати документи в XML, а потім конвертувати їх в різні формати, в тому числі HTML і PDF. DocBook також надає схему, визначальну набір шаблонів для використання технічними письменниками.

У лістингу 7 наведено приклад використання Ant, XSL-сторінки з поставки DocBook, а також форматуючих об'єктів XSL (XSL-FO) для генерації користувальницької документації в форматі PDF (див. Розділ ресурси ).

Лістинг 7. Створення документів PDF за допомогою Ant, DocBook і FO

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

Малюнок 5. Фрагмент користувальницької документації в форматі PDF

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

Документацію необов'язково створювати вручну

Я сподіваюся, що прочитавши цю статтю, ви переконалися, що існують ефективні підходи до автоматичного створення документації. На мій погляд, найважливіше в документації - це обмін інформацією, а не процес генерації документів. За допомогою засобів і способів автоматизації, описаних в цій статті, ви зможете підтримувати свою документацію в точній і актуальному стані. Це допоможе вам вирішити проблему старіння інформації - головну причину недостатнього використання документації.

Ресурси для скачування

Схожі тими

• Оригінал статті: Automation for the people: Pushbutton documentation (Пол Дюваль, developerWorks, червень 2008 р.) (EN)
• Ознайомтеся з маніфестом Методології гнучкої розробки Додатків . (EN)
• Прочитайте Цю статтю: Побудова UML-діаграм с помощью UMLGraph (Діомідіс Спінелліс, Diomidis Spinellis, Афінський університет економіки і бізнесу), що включає перелік опцій, які підтримуються UMLGraph, для створення діаграм класів. (EN)
• Ознайомтеся з прикладами діаграм, представлених в галереї GraphViz на сайті graphviz.org. (EN)
• прочитайте статтю Документування коду за 10 хвилин (Пітер Чен, Peter Chen, The Code Project, січень 2003), що описує конфігурацію Doxygen. (EN)
• Найсвіжішу інформацію про використання Doxygen в Ant можна отримати в блозі розробника завдання Ant для виклику Doxygen . (EN)
• Поради з написання корисною Java-документації можна знайти в статті Теорія і практика Java: мені правда треба документувати ЦЕ? (Брайан Гетц, Brian Goetz, developerWorks, серпень 2002 р.) (EN)
• Відвідайте домашню сторінку XSL і FO - технологій стильових сторінок, що мають статус рекомендацій консорціуму W3C. (EN)
• У Книзі Повний керівництва по XSL в DocBook (4-е видання) (Боб Стейтон, Bob Stayton, Sagehill Enterprises, 2007) описуються всі аспекти по роботі із засобами публікацій, наданих DocBook, включаючи установку, використання, а також конфігурація таблиць стилів і засобів обробки документів. (EN)
• У 30-му розділі чудовою книги Потужні засоби Java (Джон Фергюсон, John Ferguson Smart, O'Reilly, 2008 року) наводиться опис SchemaSpy, UMLGraph і Doxygen. (EN)
• Дізнайтеся більше про написання технічної документації в XML, вивчивши матеріали developerWorks, присвячені DocBook . (EN)
• Ant : Завантажте Ant і почніть збирати ваші програми надійним і передбачуваним способом. (EN)
• Grand : Завантажте Grand і створюйте діаграми, які описують скрипти Ant. (EN)
• SchemaSpy : Завантажте SchemaSpy, який дозволяє створювати ER-діаграми, що описують схеми баз даних. (EN)
• Doxygen : Завантажте Doxygen, який дозволяє генерувати докладну документацію по вихідного коду. (EN)
• UMLGraph : Завантажте UMLGraph, який надає можливість автоматичного створення UML-діаграм з вихідного коду. (EN)
• DocBook : Завантажте DocBook і генеруйте документацію в різних форматах. (EN)

Підпішіть мене на ПОВІДОМЛЕННЯ до коментарів