(В оригинале - Record your rationale)

В сообществе разработчиков часто ведутся дебаты о ценности документации, особенно по отношению к дизайну ПО. Наиболее спорные моменты – осознание ценности «авансового» детального проектирования и сложности поддержания документации в актуальном состоянии при каждом изменении кода.

Один из способов документирования, не требующий больших усилий и почти всегда окупающийся – запись логических обоснований принятия решений при проектировании. Как объяснялось в статье «Все сразу получить невозможно», архитектура – это набор принятых решений о выборе той или иной возможности из факторов качества, стоимости, времени и других характеристик. И должно быть ясно как для вас, так и для вашего руководства, разработчиков и других заинтересованных сторон, почему было принято то или иное решение, и какие альтернативы оно затрагивает (Пожертвовали ли вы масштабируемостью для снижения стоимости аппаратной части и лицензионного ПО? Безопасность настолько важна, что для ее обеспечения допустимо было повысить время реакции системы?)

Точный вид такой документации может произвольно меняться в зависимости от требований проекта, начиная от заметок в текстовом файле, wiki или блоге до использования формальных шаблонов для записи всех возможных аспектов принятых архитектурных решений. Но каким бы ни был формат, документация должна давать ответ на вопросы «Какое решение было принято» и «Почему это решение было принято». Второй вопрос, часто задаваемый, и который поэтому тоже должен быть задокументирован – «Какие альтернативы были рассмотрены, и почему они не были приняты» (обычно такой вопрос задают в форме «Почему мы не реализуем мое решение»). Документация также должна быть удобной для поиска, чтобы ответ на нужный вопрос было всегда легко найти.

Такая документация может оказаться полезной во многих разных ситуациях:

• Как способ коммуникации с разработчиками по поводу важных архитектурных принципов, которым они должны следовать
• Для предотвращения «мятежа» разработчиков, когда они захотят получить ответ на вопрос о логике, стоящей за архитектурой (или даже для скромного принятия критики, если эта критика не приводит к отмене решения в результате его пристального рассмотрения)
• Чтобы показать менеджерам и заказчикам, почему ПО было сделано именно так, как оно сделано, включая дорогие части аппаратных и программных компонент
• При переносе проекта на новую архитектуру (как часто вам доставался в наследство кусок ПО вместе с желанием понять, почему дизайнер сделал его именно так?)

Однако, самые важные плюсы этой практики – это то, что:

• Вам приходится явно указывать причины для того, чтобы убедиться, что ваши обоснования целостны (смотри статью «Проверяйте предположения»)
• Результат может использоваться как стартовая точка для пересмотра решения, когда условия, повлиявшие на предыдущее решение, поменяются.

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

Автор оригинала - Timothy High