С чего все началось
На одном из проектов мне понадобилась подсистема динамических констант: константы создаются программно, могут быть периодическими, могут хранить списки значений, и у всего этого — программный интерфейс из трех методов. Задача на пару дней, если сесть и писать код.
Но я сначала сел и написал технический проект. Восемь страниц: объекты метаданных, сигнатуры API, алгоритмы, блокировки, обработка ошибок, план тестирования.
Коллега, увидев это, спросил ровно то, что вынесено в заголовок: «А зачем? Подсистема на три метода. Ты бы уже код дописал».
Дописал бы. А потом переписал бы. Дважды. Ниже объясню, почему я в этом уверен, — но сначала договоримся о терминах, потому что половина споров про ТП происходит из-за того, что спорящие называют этим словом разные вещи.
Технический проект — это не техническое задание
ТЗ отвечает на вопрос «что должно получиться» и пишется языком заказчика: «константы можно создавать программно», «константы могут быть периодическими».
Технический проект отвечает на вопрос «как это будет устроено» и пишется языком разработчика:
- какие объекты метаданных создаем и почему именно такие;
- как выглядят сигнатуры API до последнего параметра;
- где транзакции и какие управляемые блокировки;
- что происходит в граничных случаях: константа уже существует с другими признаками, пустая дата у периодической константы, чтение несуществующей константы;
- как это все проверяется.
Ключевое отличие: ТЗ утверждает заказчик, ТП — это разговор разработчика с самим собой и с будущим сопровождением. И вот этот разговор, по моему опыту, экономит больше всего времени.
Честные аргументы «против»
Начну с позиции оппонентов, потому что она не глупая.
«Документ устареет через неделю». Правда — если документ живет в вакууме. Мой ТП за время проекта прошел версии с 1.0 до 1.9: добавились формы, роль администратора, функция поиска по значению. Устарел бы он, если бы я его не обновлял. Но обновление раздела ТП занимает десять минут, а вот восстановление проектных решений из головы уволившегося разработчика — недели.
«Код и есть документация». Код отвечает на вопрос «как сделано», но молчит о «почему». Почему значения непериодических констант хранятся под фиксированной служебной датой? Почему в подсистеме намеренно нет кэширования? Из кода это не прочитать — только из ТП, где решение зафиксировано вместе с обоснованием: «значение может измениться в течение сеанса, а инвалидация кэша усложнит подсистему».
«Мы аджайл, у нас требования меняются». Меняются. У меня за проект сменились: состав ролей, имена по стандартам, появилась форма, которой в исходных требованиях не было вовсе. ТП это не отменило — наоборот, каждое изменение ложилось в документ отдельной версией, и всегда было видно, что и почему поменялось.
Так что аргументы «против» — на самом деле аргументы против мертвого ТП. Против живого у меня контраргументов не нашлось.
Что ТП дал на практике: разбор кейса
Теперь конкретика — что произошло благодаря тому, что документ был написан до кода.
1. Главное архитектурное решение было принято на бумаге, а не в отладчике
Значения констант надо где-то хранить. Вариантов минимум три: справочник с реквизитом, регистр сведений с датой-измерением, периодический регистр сведений. На бумаге сравнение заняло полчаса, и победил периодический независимый регистр с ведущим измерением-ссылкой: срез последних из коробки, автоочистка при удалении константы, одна структура для периодических и непериодических констант (вторым — фиксированный служебный период).
Если бы я начал с кода, я бы почти наверняка начал со справочника — он «проще». А на требовании периодичности переписал бы хранение целиком, вместе с уже написанными тестами.
2. Сигнатуры API стали контрактом до первой строки реализации
В ТП были зафиксированы сигнатуры:
ДинамическиеКонстанты.СоздатьКонстанту(ИмяКонстанты, ЭтоПериодическаяКонстанта,
СодержитСписокЗначений, ДатаУстановкиЗначения, Значение)
ДинамическиеКонстанты.ПолучитьКонстанту(ИмяКонстанты, ДатаЗначения)
Плюс поведение в граничных случаях — то, о чем на этапе «сразу в код» никто не думает, а потом это всплывает в бою:
- повторное создание с теми же признаками — идемпотентно, возвращается существующая ссылка;
- создание с другими признаками — исключение, а не тихая перезапись;
- чтение несуществующей константы —
Неопределено, а не исключение.
Каждое из этих решений — это чей-то будущий несостоявшийся баг. Дешевле всего они решаются в документе.
3. План тестирования из ТП превратился в тестовый модуль
Раздел «План тестирования» из десяти пунктов почти механически развернулся в модуль на YAxUnit: пять наборов, под тридцать тестов, включая негативные сценарии с проверкой текстов исключений. Когда тестируешь по плану из ТП, а не «что вспомнилось», покрытие получается систематическим: у меня, например, в плане с самого начала стоял пункт «чтение на дату до первой записи истории» — сценарий, который при тестировании «по памяти» забывают почти всегда.
4. Первый прогон: 27 из 29 — и оба падения окупили тесты целиком
Честность требует сказать: первый прогон не был зеленым. 27 из 29, два падения. И вот тут проявилась настоящая ценность связки «ТП + тесты»:
- Первое падение оказалось дефектом самого теста — утверждение фреймворка не поддерживало мутабельное значение. Пять минут на исправление.
- Второе вскрыло вещь поинтереснее: тесты выполнялись во внешней транзакции, и ожидаемое исключение внутри транзакции API делало внешнюю транзакцию обреченной — вложенных транзакций в 1С, как известно, нет. В бою это ударило бы по любому прикладному коду, который вызывает API из своей транзакции.
Итогом стали не только два исправленных теста, но и изменение продукта (валидации параметров вынесены до открытия транзакции) и новый абзац в ТП с предупреждением для прикладников. Второй прогон — 30 из 30, ноль ошибок. Тест, написанный по плану из ТП, нашел архитектурный нюанс, который ни одно ручное тестирование не поймало бы.
5. Каждая доработка знала свое место
Дальше подсистема жила обычной жизнью доработок: форма управления константами, создание констант из формы, редактор значений всех типов конфигурации, поиск и замена значений, роль с полными правами. Каждая доработка начиналась с обновления соответствующего раздела ТП — и дважды это меняло решение еще до кода. Например, «замена значений» на бумаге сразу превратилась из «заменить значение константы» в «заменить с сохранением дат исторических записей и с точечной заменой элементов внутри списков» — в коде до этих нюансов я дошел бы через баг-репорт.
Неожиданный аргумент: ИИ-ассистенты
А теперь наблюдение последних лет, которое перевернуло мое отношение к вопросу окончательно.
Часть кода этой подсистемы писалась с ИИ-ассистентом. И выяснилась простая вещь: качество сгенерированного кода прямо пропорционально качеству спецификации на входе. Если скормить ассистенту требование «сделай подсистему констант», получите усредненную подсистему с решениями «как обычно делают» — включая чужие ошибки. Если скормить ТП с зафиксированными сигнатурами, структурой хранения, поведением граничных случаев и планом тестирования — получите код, который делает то, что спроектировали вы.
Технический проект оказался идеальным промптом. Парадокс: инструмент, который «пишет код за нас», сделал документ, описывающий этот код, не менее, а более ценным. Проектирование окончательно отделилось от набора текста программы — и осталось единственной частью работы, которую нельзя делегировать без потери смысла.
Когда ТП действительно не нужен
Чтобы не превращаться в секту свидетелей документации, честно перечислю ситуации, где я сам ТП не пишу:
- Прототип на выброс. Проверяем гипотезу, код умрет через неделю. Документировать нечего — но важно, чтобы прототип действительно умер, а не поехал в прод.
- Доработка в один экран. Новый реквизит, колонка в отчете, поправка в запросе. Достаточно нормального описания задачи и коммита.
- Работа внутри жесткого фреймворка. Если БСП или архитектура конфигурации уже продиктовала все решения, проектировать нечего — надо просто следовать стандарту.
- Одноразовая обработка. Перенос данных, разовая чистка. Максимум — чек-лист прогона.
Мой критерий простой: ТП нужен там, где есть решения, которые больно менять после реализации. Структура хранения, контракт API, схема блокировок, права — больно. Цвет кнопки — нет.
Минимальный состав, который окупается
Если писать ТП «по ГОСТу», он умрет под собственным весом. Мой рабочий минимум — 5–8 страниц:
- Назначение и ограничения — включая то, чем подсистема заниматься не будет.
- Объекты метаданных — таблицами: имя, синоним, тип, назначение каждого реквизита.
- Программный интерфейс — сигнатуры с параметрами, возвращаемыми значениями и граничными случаями.
- Ключевые алгоритмы — только нетривиальные: транзакции, блокировки, срезы.
- Обработка ошибок — таблица «ситуация → поведение».
- План тестирования — он же будущий состав юнит-тестов.
И два правила жизни документа: версия меняется с каждой доработкой, а спорные решения записываются вместе с отвергнутыми альтернативами — через год вопрос «а почему не сделали через справочник?» закрывается одним абзацем.
Выводы
Нужен ли технический проект при разработке? Мой ответ после этого проекта: нужен — везде, где есть архитектурные решения, и вреден — как ритуал.
- ТП — это не отчетность, а дешевый способ совершить ошибки на бумаге вместо продакшена.
- Живой ТП с версиями — это память проекта: «почему так» переживает и релиз, и ротацию команды.
- План тестирования в ТП — половина будущего тестового модуля; в моем случае тесты по этому плану нашли транзакционный нюанс, который стоил бы боевого инцидента.
- С приходом ИИ-ассистентов хорошая спецификация стала не архаикой, а главным рычагом качества: код теперь пишется быстро, а вот думать по-прежнему приходится самому.
- И — не пишите ТП на одноразовые обработки. Серьезно.
А как у вас: пишете технический проект перед разработкой, ограничиваетесь ТЗ или считаете, что лучшая документация — это код? Расскажите в комментариях, особенно интересны случаи, когда отсутствие (или наличие) ТП дорого обошлось.