نمونه: توسعه‌ی آگاه از مستندات

این نوشته فقط یک نمونه‌ی آزمایشی است و ادعایی درباره‌ی تجربه یا دیدگاه شخصی نویسنده ندارد.

از تصمیم آغاز کنید

بازبینی یک تغییر کد زمانی ساده‌تر است که دلیل آن دیده شود. در این گردش‌کار نمونه، تصمیم پذیرفته‌شده پیش از تبدیل شدن به وظیفه‌ی پیاده‌سازی، به مشخصاتی آزمون‌پذیر تبدیل می‌شود. زنجیره عمداً کوتاه است: ADR → SPEC → TASK → CODE.

هدف، تولید مستندات بیشتر نیست. هدف این است که محدودیت شکل‌دهنده‌ی تغییر آن‌قدر به خود تغییر نزدیک بماند که بازبین بتواند هم‌راستایی این دو را بیازماید.

قرارداد را آزمون‌پذیر نگه دارید

مشخصات باید یک نتیجه‌ی مشاهده‌پذیر را نام ببرد. سپس وظیفه می‌تواند کوچک‌ترین تغییری را انتخاب کند که آن نتیجه را اثبات می‌کند و شواهد نیز آنچه واقعاً رخ داده است ثبت می‌کنند.

type Stage = 'adr' | 'spec' | 'task' | 'code';

const trace = (stages: Stage[]) =>
  stages.every((stage, index) => index === 0 || stage !== stages[index - 1]);

جداسازی شناسه‌های فنی

دستور npm run check، شناسه‌ی translationKey و نشانی https://example.com/system-boundary حتی در میان متن فارسی جهت چپ‌به‌راست خود را حفظ می‌کنند.

حرکت میان وضعیت‌های صریح

این گردش‌کار زمانی مفید است که هر گذار، مالک روشن و آزمون قابل‌مشاهده داشته باشد. یک وظیفه‌ی پیش‌نویس نمی‌تواند تصمیم پذیرفته‌شده را پنهانی کنار بزند و یک وظیفه‌ی تمام‌شده نمی‌تواند به شواهدی تکیه کند که هرگز ثبت نشده‌اند.

مرحله	پرسش	شاهد
ADR	چرا این مسیر؟	تصمیم پذیرفته‌شده
SPEC	چه چیزی باید دیده شود؟	معیار آزمون‌پذیر
TASK	کوچک‌ترین تغییر چیست؟	فرمان‌ها و تصاویر

شکل نمونه: بازخورد پیاده‌سازی به مرز تصمیم بازمی‌گردد و در کد ناپدید نمی‌شود.

فاصله را بازبینی کنید

خطر عملی، فاصله است: تصمیم در یک محل، وظیفه در محلی دیگر و آزمونی که رابطه‌ی آشکاری با هیچ‌کدام ندارد. یک سابقه‌ی کوچک ردیابی‌پذیری این فاصله را کم می‌کند، بی‌آنکه وانمود کند مستندات جای قضاوت را می‌گیرند.^۱

پرسش بازبینی ساده می‌ماند: آیا فردی دیگر می‌تواند دلیل، قرارداد، تغییر و شاهد را دنبال کند، بی‌آنکه مجبور باشد تمام تاریخچه‌ی پروژه را از نو بسازد؟

این یادداشت محتوای آزمایشی برای بررسی ریتم پانویس و ناوبری صفحه‌کلید است. ↩