داک طراحی: چی توش بنویسیم و کِی اصلاً ننویسیم
خلاصهٔ کاملتر
مایکل لینچ که تو گوگل، مایکروسافت و شرکتهای خودش داک طراحی نوشته، تو این مطلب — برشی از کتاب Refactoring English — رویکردش به نوشتن یه داک طراحی مؤثر رو توضیح میده. به گفتهٔ اون، نوشتن داک شما رو مجبور میکنه قبل از هدر دادن وقت روی پیادهسازی اشتباه، تصمیمهای سخت رو بگیرید، و بهترین راهیه که تصمیمهای طراحی بین همتیمیها و تیمهای شریک هماهنگ بشه.
کِی بنویسیم؟ نویسنده یه چکلیست میده: چند نفر قراره هماهنگ کار کنن؟ پروژه بیشتر از سه ماه کار تماموقت میبره؟ قراره چند سال تو پروداکشن بمونه؟ همکاری بینتیمی داره؟ اهداف و نیازمندیها مبهمان؟ ریسک فاجعهباری هست که سرِ طراحی بشه جلوش رو گرفت، مثل حفرهٔ امنیتی یا ریسک حقوقی؟ اگه جواب یکی از اینها مثبت باشه احتمالاً ارزشش رو داره؛ اگه دوتا یا بیشتر مثبت باشه، تقریباً حتماً.
دربارهٔ حجم داک هم قانون جهانی نداریم، دقیقاً مثل اینکه هیچ قانونی نمیگه چقدر باید کدت رو تست کنی. داک میتونه یه صفحه باشه یا ۵۰ صفحهای که پنج تیم باید تأییدش کنن؛ اندازهٔ درست به اهداف، ریسکها، ددلاینها و فرهنگ تیم بستگی داره. لینچ صریح میگه گاهی مقدار درستِ سرمایهگذاری روی داک طراحی، صفره.
مهمترین ایدهٔ مطلب همینجاست: اگه هر جزئیاتی رو تو داک مشخص کنی، عملاً تو فاز طراحی پیادهسازی رو نوشتی و کل هدف داک از بین رفته. معیار سادهست: جریمهٔ اشتباه بودن چیه؟ اگه وباپت رو با C++ بسازی و ۲۰۰ هزار خط بعد بفهمی Ruby on Rails انتخاب بهتری بود، گیر افتادی و بازنویسی از صفر هم جواب نمیده. ولی اینکه لیست هزارتایی مقاله یکجا بیاد یا بیستتا بیستتا با دکمهٔ Load more، یه تصمیم چندساعتهست، نه دغدغهٔ سطح طراحی؛ سرِ همچین چیزی نباید وقت ریویو سوزوند.
بعد سراغ اجزای داک میره و تأکید میکنه لازم نیست همهٔ بخشها تو هر داکی باشن — زیرمجموعهٔ درست رو خودت انتخاب کن. عنوان باید کوتاه، متمایز و گویا باشه (مثلاً RecencyBank برای یه لایهٔ کش، نه «پروژهٔ اسب نقرهای پرنده»). متادیتا (نویسنده، تاریخ ساخت، آدرس معتبر)، هدف در یک جمله، پسزمینه (چرا این پروژه، چه مشکلی رو حل میکنه، قبلاً چه تلاشهایی شده) و مستندات مرتبط، ستون اول داکن.
اهداف باید بر حسب اثر نوشته بشن، نه جزئیات پیادهسازی: «کوبرنتیز رو به زیرساخت اضافه کنیم» هدف بدیه و «قطعیهای مربوط به دیپلوی نسخههای جدید رو کم کنیم» هدف خوب. کنارش non-goalها مرز بیرونی پروژه رو مشخص میکنن و سناریوها تصویر عملی سیستم تمامشده رو برای خواننده میسازن.
دیاگرام همون تصویر ذهنیای رو که تو سر نویسنده هست به ریویوئر منتقل میکنه؛ توصیهٔ لینچ اینه که ابزار قابلویرایش انتخاب کنی — Excalidraw و draw.io یا زبانهایی مثل Mermaid و D2 — نه عکس گرفتن از وایتبرد که بعداً نمیشه ویرایشش کرد. واژهنامه، محدودیتها، SLOها (آپتایم، تأخیر، مقیاس)، مانیتورینگ و هشدار، تایملاین با مایلستونهای قابلتحویل و بخش اینترفیسها (UI، API/CLI، فرمت فایل) بقیهٔ اسکلت داکن.
چند بخش هم راحت فراموش میشن ولی گرون تموم میشن: وابستگیها و زیرساخت (زبان، سختافزار، محل ذخیرهٔ داده — با این نکته که عوض کردن زبان یا استوریج سخته، ولی عوض کردن سرویس ایمیل یه بعدازظهر وقت میبره)، امنیت (تهدیدها، سطح حمله، مرزهای اعتماد)، حریم خصوصی، ملاحظات حقوقی و لاگینگ. آخر داک هم «مسائل باز» (مشکل، گزینهها، قدم بعدی)، «مسائل حلشده» و «گزینههای بررسیشده» میان؛ به گفتهٔ نویسنده چند خط کوتاه براشون کافیه، نه مستندسازی وسواسی هر ایدهٔ ردشده. قدم آخر هم بردن داک جلوی تیم برای بازخورده.
نکات کلیدی:
- داک طراحی وقتی میارزه که پروژه چندنفره، چندماهه، بینتیمی، مبهم یا پرریسک باشه؛ گاهی جواب درست اصلاً ننوشتنه
- معیار ورود هر تصمیم به داک: «جریمهٔ اشتباه بودن چیه؟» — تصمیم برگشتناپذیر آره، تصمیم چندساعته نه
- اهداف رو بر حسب اثر بنویس نه جزئیات پیادهسازی؛ non-goalها مرز پروژه رو روشن میکنن
- بخشهای فراموششده ولی گرانقیمت: امنیت، حریم خصوصی، وابستگیها، لاگینگ و SLO
- دیاگرام رو با ابزار قابلویرایش بکش و داک رو برای بازخورد جلوی تیم بذار
