В идеале, конечно, код должен сам себя документировать, но практика показывает, что содержать хорошую документацию по большому проекту довольно сложно, и в некоторых условиях может быть нереальным. Но никакой самый совершенный код не заменит наглядную диаграмму, смотря на которую тут же понимаешь структуру кода. (особенно если workflow посложней, чем изображен в примере)
Сегодня наткнулся на плагин PlantUML, который позволяет делать такую графическую документацию прямо в коде. Текстовый эквивалент диаграммы, которая изображена выше будет выглядеть вот так:
@startuml (*) --> "Показать картинку" --> "Спросить мнение" If "Нравится?" then --> [Да] "Добавить в коллекцию" --> "Отправить результат" else --> "Отправить результат" Endif -->(*) @enduml
А в IDE вот так:
При клике на файл в редакторе отображается его текстовая версия, а плагин на ходу формирует графическое представление. Удобно располагать такую подсказку прямо около описываемого кода, тогда разработчику не надо тратить время на поиск документации. Система контроля версий позволит наглядно отследить эволюцию workflow. Не хватает только наглядного диффа в виде диаграмм, пока дифф доступен только для текстового эквивалента.
Плагин позволяет строить множество различных типов диаграмм, примеры можно посмотреть на их сайте. Чтобы добавить в свой проект поддержку графической документации, нужно сделать три шага (я использую Intellij Idea):
- Установить плагин PlantUML integration
- Установить плагин PlantUML syntax check
- Загрузить здесь graphivz - графическую библиотеку, которую использует плагин для рисования диаграмм.
После перезапуска появятся новые пункты меню UML, которые будут создавать минимально заполненный шаблон диаграммы для последующего редактирования.
Комментариев нет :
Отправить комментарий