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

- «Так исторически сложилось.»

Обычно за этим следует длинное описание того, как система пришла к своему текущему состоянию. И, как правило, это история о том, что когда-то было принято сиюминутное решение, которое потом обросло новыми слоями, костылями и компромиссами. И теперь никто точно не помнит, почему всё работает именно так.

Проблема без документации

Всё это, в целом, хорошо бы записать. Хотя бы создать базовую документацию. Но этого почти никто не делает.

Мы ведь знаем, что у нас есть куча подходов и разнообразный инструментарий для создания и ведения документации! Сам практикую подход «Docs as Code» — документация как код. Он прост, при минимальном усердии даёт отличный результат, помогает держать документацию в тонусе и органично вписывать её в жизненный цикл разработки.

И всё равно документации нет. Почему?

Вопрос не праздный. Регулярно работая с легаси-кодом, натыкаюсь на несоответствие кода и задачи. Это приводит к трате времени на распутывание — помимо кода, ещё и основной мысли самой программы.

Казалось бы, ответ простой: лень.

Но лень в этом смысле должна помогать! Написать один раз — и по сто раз не объяснять, как всё работает. Это же экономия сил! Но нет — многие выбирают путь бесконечных устных объяснений.

Чаще мне встречается другой ответ:

- «Мы не подумали, что это важно.»

И это, пожалуй, главная ловушка. Окрылённые желанием сделать быстро и получить результат, разработчики и заказчики скатываются в неё. И осознают это только после определённых событий — когда проект разрастается, команда меняется, а ответить на вопрос «почему здесь такое решение?» становится просто некому.

Время AI-помощников

Сегодня у нас есть различные AI-помощники, которые уже на этапе старта могут дать анализ структуры проекта по описанию. Используйте эти возможности!

Стройте хотя бы базовую документацию в виде простейшего описания мысли по контексту, модулю — всего, что делаете. Это даст в будущем прирост понимания:

- Какого результата ожидать - Действительно ли вы двигаетесь в выбранном направлении - Или уже свернули с дороги, превратившись в совсем другой проект

У нас есть инструменты, которые реально работают!

Есть BDD-спецификации, которые описывают поведение системы с точки зрения пользователя.

Есть запись в стиле «Архитектурные решения» (ADR) — простой формат, где фиксируется:

- Контекст (почему мы здесь оказались) - Рассмотренные варианты - Принятое решение - Последствия

Эти подходы позволяют фокусироваться на старте, не отнимая желания творить. Тем более, всё равно придётся каким-то образом возвращаться к истокам и «самому себе составлять ТЗ».

Главный вывод

Время, потраченное на документацию, не проходит даром. Оно окупается с лихвой.

Через год вы не вспомните, почему приняли то или иное решение. Но если оно записано — вы сможете не только вспомнить, но и объяснить команде, новым разработчикам и даже себе будущему.

#документация #DocsAsCode

«А как у вас с документацией? Есть ли в проектах описание архитектуры или живёте в режиме «так исторически сложилось»?» 👇