ADR: چرا تصمیم‌های معماری باید نوشته شوند
شش ماه بعد کسی یادش نیست چرا این پایگاه داده یا این ساختار انتخاب شد. ثبت تصمیم معماری یا ADR، سندی یک‌صفحه‌ای است که دلیل هر تصمیم مهم را نگه می‌دارد و جلوی بحث‌های تکراری را می‌گیرد.
در هر پروژه‌ی نرم‌افزاری لحظه‌ای می‌رسد که کسی می‌پرسد: «چرا این را این‌طور ساختیم؟» و هیچ‌کس جواب دقیقی ندارد. کسی که تصمیم گرفته بود رفته، یا یادش نیست، یا دلیلش دیگر معتبر نیست ولی کسی نمی‌داند.
ثبت تصمیم معماری یا ADR پاسخ ساده‌ای به این مشکل است.
ADR چیست
ADR مخفف Architecture Decision Record است: یک سند کوتاه، معمولاً یک صفحه، که یک تصمیم مهم را ثبت می‌کند. نه مستندات کل سامانه؛ فقط یک تصمیم، دلیلش و پیامدهایش.
قالب ساده
یک ADR خوب چهار بخش دارد:
- زمینه: چه وضعیتی باعث شد این تصمیم لازم شود؟ چه قیدهایی داشتیم؟
- تصمیم: چه چیزی را انتخاب کردیم؟ در یک یا دو جمله.
- گزینه‌های دیگر: چه چیزهایی را بررسی و کنار گذاشتیم، و چرا؟
- پیامدها: این تصمیم چه چیزی را آسان و چه چیزی را سخت می‌کند؟
بخش سوم مهم‌ترین و فراموش‌شده‌ترین بخش است. تصمیمی که گزینه‌های ردشده‌اش نوشته نشده باشد، شش ماه بعد دوباره به بحث گذاشته می‌شود.
یک مثال واقعی
این یکی از تصمیم‌های ثبت‌شده در ساخت همین سایت است، به شکل خلاصه:
زمینه: سایت باید در محیط توسعه بدون هیچ نصب و راه‌اندازی اجرا شود، ولی در محیط عملیاتی پایگاه داده‌ی قابل‌اتکا داشته باشد.
تصمیم: در توسعه یک پایگاه داده‌ی فایل‌محور و در عملیات PostgreSQL؛ هر دو پشت یک قرارداد یکسان.
گزینه‌های دیگر: فقط PostgreSQL در همه‌جا (راه‌اندازی محلی را سنگین می‌کرد)؛ فقط پایگاه فایل‌محور (برای عملیات محدودکننده بود).
پیامدها: هر تغییر ساختار داده باید برای هر دو نوشته شود. در عوض، هر توسعه‌دهنده با یک دستور محیط کامل دارد.
همین چند خط، پاسخ پرسشی است که بدون آن بارها تکرار می‌شد.
چه تصمیم‌هایی ارزش ثبت دارند
همه‌ی تصمیم‌ها ADR نمی‌خواهند. این‌ها می‌خواهند:
- تصمیم‌هایی که برگرداندنشان گران است: پایگاه داده، ساختار ماژول‌ها، روش احراز هویت.
- تصمیم‌هایی که خلاف انتظار هستند و بعداً سؤال‌برانگیز می‌شوند.
- تصمیم‌هایی که یک بده‌بستان آگاهانه دارند: چیزی را فدای چیز دیگر کرده‌اید.
- تصمیم به انجام ندادن کاری. این‌ها هم باید ثبت شوند.
انتخاب نام یک متغیر ADR نمی‌خواهد.
قاعده‌های نگهداری
- کوتاه بنویسید. ADR ده‌صفحه‌ای را کسی نمی‌خواند.
- تغییرش ندهید؛ جایگزینش کنید. اگر تصمیم عوض شد، ADR جدیدی بنویسید که قبلی را منسوخ می‌کند. تاریخچه ارزش دارد.
- شماره بزنید و کنار کد نگه دارید. سندی که از کد جداست، کهنه می‌شود.
- همان موقع بنویسید. دو هفته بعد، نیمی از دلایل را فراموش کرده‌اید.
فایده برای کارفرما
ADR فقط ابزار تیم فنی نیست. برای صاحب محصول سه فایده‌ی مستقیم دارد:
- وابستگی به افراد کم می‌شود. اگر عضوی از تیم برود، دلیل تصمیم‌هایش نمی‌رود.
- هزینه‌ی ورود نیروی جدید پایین می‌آید. خواندن چند ADR، ماه‌ها پرسیدن را کوتاه می‌کند.
- تصمیم‌ها قابل‌دفاع می‌شوند. وقتی سرمایه‌گذار یا ممیز فنی می‌پرسد «چرا»، پاسخ مکتوب وجود دارد.
جایگاه ADR در روش کار
در روش کار من، ثبت تصمیم‌های معماری یکی از خروجی‌های گام سوم است، کنار نقشه‌ی سامانه، قرارداد API و مدل داده. یکی از اصول ثابت کار هم همین است: تصمیم‌ها مکتوب می‌شوند تا بعداً قابل‌دفاع باشند.
ADRها مکمل PRD هستند: PRD می‌گوید چه چیزی و چرا ساخته می‌شود؛ ADR می‌گوید چرا این‌طور ساخته شد.
جمع‌بندی
نوشتن یک ADR ده دقیقه وقت می‌گیرد و جلوی ساعت‌ها بحث تکراری را می‌گیرد. مهم‌تر اینکه محصول را از حافظه‌ی افراد مستقل می‌کند.
مطلب مرتبط: بدهی فنی: چه زمانی آن را بپذیریم.