Спецификации вместо кода

Всё чаще замечаю, что код перестаёт быть самым дефицитным результатом работы программиста. Дефицитом становится понимание того, как устроена система и почему она работает именно так.

У нас много старых проектов на «Битриксе». Некоторым уже около десяти лет.

За это время проект может несколько раз сменить разработчика, пережить обновление PHP, замену модулей и новые интеграции с 1С. Какие-то части переписываются, другие годами остаются нетронутыми.

В таких проектах постепенно появляется собственная внутренняя логика, которую со стороны уже не видно.

Например, есть файл old_import.php. По названию кажется, что это остаток старой версии и его давно пора удалить. Но именно через него каждую ночь прилетает часть данных из 1С.

Или есть странное поле в заказе, которое вроде бы дублирует стандартное. Удалить его нельзя: на него завязана интеграция, написанная пять лет назад.

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

Раньше такая модель постепенно формировалась в процессе самой разработки. С ИИ до готового кода теперь можно дойти намного быстрее.

Можно открыть проект, попросить добавить авторизацию по SMS и через несколько минут получить вполне хорошую реализацию.

Но готовый код сам по себе почти ничего не расскажет о контексте проекта.

Поэтому тут я вижу пользу спецификаций.

И я не про технические задания, которые пишутся до начала проекта и устаревают ещё до его запуска. Речь о коротких описаниях отдельных частей системы. В них фиксируется, как всё должно работать и какие решения лучше не трогать.

Возьмём авторизацию по SMS.

Пользователь входит по номеру телефона. Код действует пять минут. Новый код отменяет предыдущий. Повторная отправка доступна через минуту, не больше пяти раз в час.

Если пользователя с таким номером нет, после подтверждения создаётся новый аккаунт.

Существующую регистрацию «Битрикса» менять нельзя. Она используется в обмене с 1С.

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

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

Вероятнее всего именно этим и будут заниматься разработчики вместе со своими Кодексами и Клодами