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

#frontend #backend

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

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

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

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

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

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

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

Сделано в Лаборатории Студии Чулакова

Студия Олега Чулакова

Дизайн-студия № 1 в России по версии Tagline, лучший usability / UX в стране по версии Золотого Сайта.

Специализируется на создании сложных систем и сервисов для крупных компаний. Среди клиентов Студии Tele2, ИКЕА, МегаФон, БКС Банк, Yota и другие крупнейшие российские бренды.