Документировать или нет — это не вопрос
#frontend #backend

Говорят, что хороший код не требует документации. И мы в это свято верим 😁 Однако наш опыт разработки проектов с длинной линией жизни показывает, что документировать все-таки необходимо, и не только код.

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

Кстати, описание RESTful API также относится к технологической документации.

Для документирования кода проектов на PHP-фреймворках мы используем phpDocumentor, который способен генерировать интерактивную документацию по специализированной метаразметке структурных единиц кода веб-приложения: модули, классы, поля и методы — все покрывается описательной частью на уровне аннотаций. При необходимости можно даже получать интерактивные аналитические отчеты по покрытию кода тестами с помощью PHPUnit.

Код реактивных приложений на React.js, Vue.js и Angular также поддается документированию. Для этого наши разработчики используют плагин Storybook Addon Notes в связке с инструментом для разработки UI-компонентов Storybook.

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

Развивать, сопровождать и переиспользовать становится легко и удобно.