2learn

Документирование решений

Что это такое

Запись об архитектурном решении — короткий документ об одном решении: ситуация, которая его вынудила, рассмотренные варианты, выбранный вариант и цена выбора. Её пишут в момент принятия решения, держат рядом с кодом и никогда потом не правят: если решение меняется, новая запись вытесняет старую, а смысл в том, чтобы сохранить рассуждение, а не описать систему.

Почему это важно

Больше всего времени в зрелой кодовой базе отнимает вопрос «почему здесь так?». Проект, который выглядит явно неверным, часто кодирует ограничение, которого больше нигде нет: бюджет задержки, правило соответствия, библиотеку с дефектом. Без записи выбор оспаривают каждый раз, когда приходит новый человек, или, что хуже, отменяют, потому что ограничение было невидимым. Запись стоит двадцать минут и экономит это собрание снова и снова.

Ключевые идеи

Записывайте решения, а не описания

Диаграмма текущей системы устаревает в тот самый момент, когда её рисуют, и читателям не хватает вовсе не её. Восстановить они не могут другое — взвешивание альтернатив: почему эта база данных, а не другая, почему эта граница, а не более простая. Записи о решениях нацелены ровно на это, поэтому остаются полезными годами, тогда как диаграммы архитектуры — нет.

контекст -> варианты -> решение -> последствия

Держите коротко и конкретно

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

название: синхронные вызовы для поиска заказов
контекст: ценообразованию нужен уровень клиента в момент оформления
варианты: синхронный HTTP (просто, добавляет режим отказа), кэшированная копия (быстро, может быть устаревшей)
решение: синхронный HTTP с тайм-аутом 200 мс и запасным уровнем
последствия: оформление отказывает в пользу уровня по умолчанию; кэш можно добавить позже

Вытесняйте, никогда не переписывайте

Правка старой записи под сегодняшнюю реальность уничтожает единственное свидетельство того, почему прежний выбор был сделан, — а это обычно и есть важная часть. Напишите новую запись, которая ссылается на старую и объясняет, что изменилось. История решений и есть объяснение того, почему система имеет такую форму.

Держите записи там, где код

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

Не каждому выбору нужна запись

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

Практика

Напишите одну запись о прошлом решении

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

Готово, когда: вы можете передать её тому, кого там не было, и он объяснит, почему альтернатива была отвергнута.

Проверьте находимость

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

Готово, когда: читатель, дойдя до модуля, находит запись, не спрашивая путь.

Частые ошибки

  • Написание описания системы вместо решения — оно устаревает сразу и отвечает на вопрос, которого никто не задавал; исправить: записывайте один выбор, его альтернативы и последствия.
  • Правка записи при изменении решения — исходное рассуждение теряется, и история не восстанавливается; исправить: добавьте новую запись, вытесняющую старую.
  • Отсутствие альтернатив в списке — читатель не может понять, рассматривались ли варианты; исправить: выпишите хотя бы один отвергнутый вариант с причиной.
  • Хранение записей вне репозитория — они расходятся с кодом, и их перестают находить; исправить: держите их рядом с кодом и ссылайтесь из модуля.
  • Запись каждого тривиального выбора — полезные записи тонут среди шума; исправить: берегите записи для решений, дорогих для отката или неожиданных.

Что читать дальше

Разобранные примеры

Файлы cookie аналитики ставятся только с вашего согласия. До вашего выбора ничего не загружается и никуда не отправляется.