ADR؛ ثبت یک تصمیم معماری در یک صفحه
خلاصهٔ کاملتر
به گفتهٔ مارتین فاولر، یه Architecture Decision Record یا ADR یه سند کوتاهه که یه تصمیم مشخص مربوط به یه محصول یا اکوسیستم رو ثبت و توضیح میده. این سند باید کوتاه باشه، در حد چند صفحه، و شامل خودِ تصمیم، کانتکستی که به خاطرش گرفته شده و پیامدهای مهمش باشه. اگه بعداً تصمیم عوض شد، ADR قدیمی نباید دستکاری بشه، بلکه به یه ADR جایگزین لینک میشه.
فاولر میگه نوشتن ADR دو هدف رو برآورده میکنه. اول اینکه یه رکورد از تصمیمهاست و میذاره آدمها ماهها یا سالها بعد بفهمن چرا سیستم اینشکلی ساخته شده. ولی شاید حتی باارزشتر این باشه که خودِ عملِ نوشتن، بهخصوص تو گروه، فکر رو شفاف میکنه؛ نوشتن یه سندِ پیامددار معمولاً دیدگاههای متفاوت رو رو میکنه و مجبورشون میکنه که بحث و امیدوارانه حل بشن. فاولر پیشنهاد میکنه سبک نوشتن مثل «هرم وارونهٔ» خبرنگاری باشه: مهمترین مطلب اول بیاد و جزئیات به بخشهای بعدی هل داده بشه.
توصیهٔ رایج اینه که ADRها تو همون ریپازیتوری کدی که بهش مربوطن نگه داشته بشن، معمولاً تو doc/adr، تا برای کسایی که رو کد کار میکنن در دسترس باشن. به همین دلیل باید با یه زبان نشانهگذاری سبک مثل markdown نوشته بشن تا مثل کد راحت خونده و diff بشن. البته فاولر میگه این روش برای ADRهایی که یه اکوسیستم بزرگتر از یه کدبیس رو پوشش میدن جواب نمیده، و بعضیها هم معتقدن نگهداری تو git کار رو برای غیربرنامهنویسها سخت میکنه.
هر رکورد باید فایل خودش رو داشته باشه و تو اسم فایل با یه شمارهٔ صعودی و یه نام گویا شمارهگذاری بشه، مثل 0001-HTMX-for-active-web-pages، تا تو لیست دایرکتوری راحت خونده بشن. هر ADR یه وضعیت داره: «proposed» موقع بحث، «accepted» وقتی تیم قبولش کرد و فعاله، و «superseded» وقتی جدی تغییر کرد یا جایگزین شد، همراه با لینک به ADR جانشین. فاولر تأکید میکنه یه ADR پذیرفتهشده هیچوقت نباید دوباره باز یا عوض بشه؛ بهجاش باید جایگزین بشه تا یه لاگ روشن از تصمیمها و مدت اعتبارشون بمونه.
به گفتهٔ فاولر، ADR فقط تصمیم نیست، یه دلیل مختصر هم داره که مسئلهٔ منجر به تصمیم و تریدآفهای در نظر گرفتهشده رو خلاصه میکنه؛ خوبه که مثل مفهوم «نیروها» تو نوشتن پترن، همهٔ گزینههای جدی بررسیشده با مزایا و معایبشون هم صریح فهرست بشن. پیامدها رو هم بهتره تو یه بخش جدا صریح بنویسی و چون تصمیمها معمولاً تو یه حدی از عدمقطعیت گرفته میشن، ثبت سطح اطمینان و اینکه چه تغییری تو کانتکست محصول باید باعث بازنگری بشه مفیده. فاولر میگه ADR تو Advice Process نقش مرکزی داره، جایی که خودِ نوشتنش برای بیرونکشیدن تخصص و همراستایی به کار میره. مهمتر از همه اختصاره؛ ADR رو کوتاه و در حد یک صفحه نگه دار و اگه مطلب پشتیبان داری، بهش لینک بده. این اصطلاح رو مایکل نایگارد سال ۲۰۱۱ ابداع کرد.
نکات کلیدی:
- ADR یه سند کوتاهه که یه تصمیم معماری، کانتکست، دلیل و پیامدهاش رو ثبت میکنه
- خودِ نوشتنش فکر رو شفاف و اختلافنظرها رو قابلبحث میکنه
- تو ریپازیتوری کد و به markdown نگه داشته میشه؛ هر رکورد یه فایل شمارهدار
- وضعیتها: proposed، accepted و superseded؛ ADR پذیرفتهشده عوض نمیشه، جایگزین میشه
- گزینههای جایگزین، تریدآفها و سطح اطمینان رو هم ثبت کن و کوتاه بنویس
