مدخل إلى ADR (سجلّ قرار العمارة) ── أقلّ وسيلة لتوثيق «لماذا اخترنا هذا التصميم» في التطوير الصغير

«لماذا يتمّ التكامل هنا عبر ملفّ؟ أليس من الأبسط النظر إلى قاعدة البيانات مباشرةً؟» ── يصطدم أيّ مطوّر يفتح شيفرة نظام ورثه بهذا النوع من الأسئلة تقريباً حتماً. وفي أغلب الأحيان، لم يعد من يعرف الإجابة موجوداً في المشروع.

لا بدّ أنّ سبباً كان موجوداً. ربّما لم يُمنح إذن الاتّصال المباشر بقاعدة بيانات النظام الآخر، أو ربّما لم تكن هناك طريقة آمنة أخرى ضمن الموعد النهائيّ آنذاك. لكن إن لم يبقَ هذا السبب مُدوَّناً، يتوقّف من يخلف صاحبه أمام «شيفرة لا يعرف هل يجوز لمسها»، أو على العكس، يهدم السبب نفسه دون أن يدري.

تناولنا في هذه المدوّنة كيفيّة السير في التطوير التعاقديّ في «ما ينبغي ترتيبه قبل طلب تطوير تطبيق Windows بالتعهيد الخارجيّ أو التعاقد»، وإطار العقد في «التمييز بين شبه التفويض والمقاولة وفق «العقود والصفقات النموذجيّة» لـ IPA». هذا المقال يذهب أبعد من ذلك، إلى موضوع «كيف نُبقي النظام صالحاً لسنوات بعد بنائه». نشرح آليّة توثيق أسباب قرارات التصميم بأقلّ جهد ممكن، وهي ADR (Architecture Decision Record)، مع افتراض تطوير تعاقديّ صغير أو تطوير داخليّ.

1. الخلاصة أوّلاً

• ينبغي توثيق «سجلّ القرار» قبل وثيقة التصميم الشاملة. فما يُصعِّب الصيانة فعلاً ليس عدم معرفة «ماذا يفعل النظام»، بل عدم معرفة «لماذا فُعِل بهذه الطريقة».
• ADR صيغة خفيفة تكتب فيها قراراً واحداً في ملفّ واحد وفق القالب الثابت «العنوان / الحالة / السياق / القرار / النتيجة». اقترحها Michael Nygard عام 2011، والمبدأ أن تكون كلّ سجلّة ضمن صفحة أو صفحتين.¹
• مكان الحفظ هو المستودع نفسه الذي يحوي الشيفرة (مثلاً: docs/adr/0001-title.md). لا يُحفَظ في Wiki أو مجلّد مشترك، بل يخضع للتحكّم بالإصدارات مع الشيفرة، ويُراجَع مع مراجعة الشيفرة.¹²
• لا تُستبدَل القرارات كتابةً فوق القديم. عند تغيير السياسة، تُضاف ADR جديدة، وتُحوَّل حالة القديمة إلى Superseded (مُستبدَلة) مع مرجع متبادل بينهما. ADR سجلّ يُضاف إليه فقط.²
• لا تُكتَب كلّ القرارات، بل فقط القرارات التي «يصعب تغييرها لاحقاً» أو «كان لها عدّة خيارات معقولة» أو «حسمها قيد ما». قواعد التسمية وإعدادات المنسِّق (formatter) خارج النطاق.²
• في تجربة الكاتب، شرط الاستمرار هو حصر كلّ سجلّ في 15 إلى 30 دقيقة من الكتابة. القالب الثقيل يتوقّف بعد أوّل 3 سجلّات.
• في التطوير التعاقديّ، يصبح ADR مُخرَجاً يمكن مشاركته مع الجهة الطالبة. يعمل كما هو كمادّة شرح عند القبول (acceptance)، ومادّة تسليم عند تبديل المسؤول أو المورِّد.

2. مشكلة «لا نعرف لماذا أصبح الأمر هكذا»

2.1 الشيفرة تخبرنا بـWhat، لا بـWhy

بقراءة الشيفرة يمكن معرفة «ماذا تفعل» (إن بُذِل الوقت الكافي). ما لا يمكن معرفته هو أسئلة «لماذا» من هذا النوع.

• لماذا قاعدة البيانات SQLite لا SQL Server؟
• لماذا التكامل مع الأنظمة الأخرى عبر تبادل ملفّات CSV لا Web API؟
• لماذا يُطبَع هذا التقرير وحده بتشغيل Excel؟
• لماذا لا يزال النظام على .NET Framework دون الترقية إلى .NET الحاليّ؟

لكلّ قرار من هذا النوع سبب موجود خارج الشيفرة بالضرورة: الميزانيّة، والموعد النهائيّ، وقيود العميل، والتوافق مع الأصول القائمة آنذاك. هذا السبب أكبر من أن يُكتَب في تعليق، و«ملابسات القرار» لا تناسب وثيقة التصميم. والنتيجة أنّ السبب لا يبقى مُدوَّناً في أيّ مكان.

2.2 أماكن حفظ القرارات كلّها تتلاشى خلال سنوات قليلة

فأين توجد أسباب قرارات التصميم فعليّاً الآن؟ لنقارن الأماكن الشائعة لحفظها.

تشير إرشادات المعماريّين لدى Microsoft بوضوح أيضاً إلى أنّ القرار غير المُدوَّن يُنسى، ما يُعيد فتح النقاش نفسه من جديد، ويجلب تعديلات تخالف النيّة الأصليّة.²

2.3 في التطوير التعاقديّ، تصبح نقطة انتهاء العقد نقطة انقطاع الذاكرة

في التطوير الداخليّ، تظلّ عبارة «اسأل فلاناً وستعرف» صالحة لفترة، لكن في التطوير التعاقديّ هناك، إضافة إلى نقل الموظّفين واستقالتهم، تبديل المورِّد (vendor) نفسه. ففي اللحظة التي يصبح فيها المورِّد المطوِّر مختلفاً عن المورِّد القائم بالصيانة، يضيع تماماً كلّ «لماذا» كان موجوداً في الحديث الشفهيّ والمحادثات.

من زاوية العقد أيضاً، من الطبيعيّ أن يكون التطوير والصيانة عقدين وعمليّتين منفصلتين (تناولنا هذه البنية في «شرح «العقود والصفقات النموذجيّة» لـ IPA»). وكما رتّبنا في «العمل الصحيح بعقد شبه التفويض»، ففي عقد شبه التفويض تحديداً، ولأنّ الجهة المتعاقدة تسير في العمل باستقلاليّة، فإنّ وجود سجلّ يُظهِر للجهة الطالبة ماذا حُكِم وكيف يصبح دعامة للثقة. ويفيد ADR في هذين الأمرين معاً.

3. ما هو ADR

3.1 اقتراح Nygard ── خمسة عناصر وحدّ أقصى صفحتان

ADR صيغة اقترحها Michael Nygard في تدوينته لعام 2011 بعنوان «Documenting Architecture Decisions».¹ أهمّ نقاطها كالتالي.

• ملفّ واحد لكلّ قرار. تُرقَّم بتسلسل، ولا يُعاد استخدام الرقم
• الملفّ بصيغة خفيفة مثل Markdown، ويوضَع داخل مستودع المشروع
• يتكوّن من خمسة عناصر: العنوان / الحالة / السياق / القرار / النتيجة (Consequences)
• تتقدّم الحالة من مقترَح (proposed) إلى معتمَد (accepted)، وعند التراجع تُصبح مُلغاة (deprecated) أو مُستبدَلة (superseded). لا يُحذَف السجلّ القديم
• الإجمالي ضمن صفحة أو صفحتين. يُكتَب بنصّ مكتمل يمكن لمطوّر مستقبليّ قراءته وكأنّه محادثة

يحمل الاسم كلمة «معماريّة (architecture)»، لكنّه ليس أسلوباً مخصَّصاً للأنظمة الكبيرة. بل على العكس، هذا «القالب الأدنى» يعمل بالضبط في التطوير الصغير الذي لا يملك معماريّاً متفرّغاً ولا مسؤول توثيق. كما أنّ قوالب وأدوات ADR منظَّمة بشكل منهجيّ في موقع المجتمع (adr.github.io)، ويمكن الرجوع إليه كمدخل لفكرة «توثيق القرارات المهمّة معماريّاً مع أسبابها ومفاضلاتها (trade-offs)».³

3.2 قالب Markdown

هذا هو القالب الأدنى الذي يستخدمه الكاتب في المشاريع الصغيرة، وهو صيغة Nygard كما هي.

# ADR-NNNN: (وصف القرار في جملة قصيرة)

## الحالة

مقترَح | معتمَد | مُلغى | مُستبدَل (→ ADR-MMMM)

## السياق

لماذا احتجنا إلى هذا القرار. اكتب الافتراضات التقنية والعملية،
والقيود (الميزانية، الموعد النهائي، الأصول القائمة، بيئة العميل)،
والخيارات التي دُرست، بحيث يفهمها قارئ لا يعرف ظروف تلك اللحظة.

## القرار

اكتب بصيغة الفعل المبني للمعلوم وبشكل حاسم: «نفعل كذا». من جملة إلى ثلاث جمل.

## النتيجة

اذكر ما يتحسّن وما يسوء بهذا القرار (المفاضلة/trade-off) معاً.
واذكر إن وُجد شرط قد يدفع مستقبلاً لإعادة النظر في هذا القرار.

النقطة المهمّة أن تُكتَب النقاط السلبيّة أيضاً في «النتيجة». فالقرار بلا مفاضلة (trade-off) لا يستحقّ التوثيق تقريباً. وتؤكّد إرشادات Microsoft أيضاً على عدم إخفاء تبعات القرار، عمداً أو عرَضاً، وأنّ السجلّ الخالي من الأسباب يفقد قيمته مع الوقت.²

4. ماذا نكتب في ADR وماذا لا نكتب

أكبر سبب لتوقّف ممارسة ADR هو «محاولة كتابة كلّ شيء». تنصّ إرشادات Microsoft على أن يقتصر التوثيق على ما يؤثّر في بنية النظام أو خصائص الجودة المهمّة، وما يصعب التراجع عنه.² وإذا طبّقنا هذا على القرارات اليوميّة، نحصل على الجدول التالي.

المعيار عند التردّد واحد: «هل سيرغب من ينظر إلى هذه الشيفرة بعد سنة (بمن فيهم أنا) في أن يسأل: لماذا؟». إن كان سيرغب، اكتبه. وإن كان بديهيّاً من الشيفرة أو الإعدادات، فلا تكتبه.

فخّ آخر هو التفكير في مستوى التفصيل بحسب «نوع الوثيقة». تحديد توزيع الأدوار كما يلي يزيل التردّد.

5. التطبيق العمليّ في التطوير التعاقديّ الصغير

5.1 المجلّد وأسماء الملفّات

يُنشَأ مجلّد docs/adr/ تحت جذر المستودع مباشرةً، وتوضَع الملفّات برقم تسلسليّ + slug قصير.

docs/
  adr/
    0001-record-architecture-decisions.md
    0002-use-sqlite-for-local-storage.md
    0003-excel-report-via-com-automation.md
    0007-excel-report-via-openxml-library.md

من المعتاد أن يكون السجلّ الأوّل هو ADR نفسها التي تقول «قرّرنا استخدام ADR». وبذلك يستطيع الخلَف فهم قواعد التشغيل نفسها بمجرّد النظر إلى docs/adr/.

5.2 متى تُكتَب، ومن يراجعها

• توقيت الكتابة هو «بعد اتّخاذ القرار مباشرةً». اجعل نتيجة الاجتماع ADR في اليوم نفسه، كخاتمة لمناقشة التصميم. كما سنرى لاحقاً، فإنّ تجميعها وكتابتها لاحقاً يفشل عادةً.
• أدرِج ADR ضمن مراجعة الشيفرة. ما عليك سوى التحقّق من أنّ طلب السحب (PR) الذي يمسّ الأسلوب يتضمّن إضافة أو تحديث ADR. لا حاجة لاجتماع اعتماد مخصَّص لـADR، وجعلها جزءاً من المراجعة هو الحلّ الواقعيّ للفرق الصغيرة. توصي إرشادات Microsoft أيضاً بوضع ADR تحت التحكّم بالإصدارات.²
• عند التراجع عن قرار، اكتب ADR جديدة، وحوّل حالة القديمة إلى Superseded مع مرجع متبادل بينهما. لا يُعاد كتابة النصّ. عدم تعديل السجلّات المعتمَدة، والحفاظ على التاريخ عبر سلسلة استبدال متتالية ── هذا هو معنى معاملة ADR كـ«سجلّ يُضاف إليه فقط».²

5.3 ADR بوصفها مُخرَجاً يُشارَك مع الجهة الطالبة

في التطوير التعاقديّ، نوصي بمشاركة ADR مع الجهة الطالبة كجزء من مُخرَجات التسليم. لذلك ثلاث فوائد.

1. تصبح مادّة للقبول (acceptance) والشرح. بدلاً من شرح «لماذا هذا التكوين» شفهيّاً، يكفي عرض ADR. والقرارات التي حسمتها قيود (الميزانيّة، الموعد النهائيّ، البيئة) تكون الجهة الطالبة نفسها طرفاً فيها، فوجود السجلّ يمنع سوء الفهم لاحقاً.
2. تصبح تأميناً عند تبديل المورِّد. من موقع الجهة الطالبة، يختلف تكلفة التسليم ومخاطره اختلافاً كبيراً بحسب وجود «تاريخ القرارات» القابل لتسليمه إلى المورِّد التالي أم لا. كما كتبنا في «دليل التطوير التعاقديّ لتطبيقات Windows» عن الترتيب قبل الطلب، فعند تحديد وقت العقد ما تحصل عليه الجهة الطالبة من وثائق تبقى بعد التسليم، يُعدّ ADR من أعلى الخيارات عائداً على التكلفة.
3. يتّسق جيّداً مع تقارير شبه التفويض. يتطلّب عقد شبه التفويض تقريراً عن سير العمل، ويمكن استخدام ADR كما هي في تقرير مرحلة التصميم.

5.4 الإحساس الواقعيّ بالوقت المستغرَق

في تجربة الكاتب، تستغرق كتابة سجلّ واحد وفق القالب 15 إلى 30 دقيقة. وتيرة القرارات في المشاريع الصغيرة عادةً بضعة قرارات شهريّاً، فباستثمار ساعة أو ساعتين شهريّاً تبقى كلّ «الأسباب» موثَّقة. وبالمقارنة مع الوقت الذي يضيع بعد سنوات في البحث وإعادة النظر والتسليم، لا يكاد يوجد موقع عمل لا يستحقّ فيه هذا الاستثمار.

6. الأخطاء الشائعة

يقع الوقوع في فخّ «الكتابة لاحقاً دفعة واحدة» تحديداً عند إدخال ADR في نظام قائم بعد بدء المشروع. الأسلوب الواقعيّ هو عدم محاولة استعادة كلّ القرارات الماضية، بل الاكتفاء بكتابة بضعة سجلّات بأثر رجعيّ للقرارات الرئيسيّة المعروفة، ثمّ البناء عليها من قرارات اليوم فصاعداً. وحتّى في الأنظمة القائمة (brownfield)، تستحقّ القرارات الماضية المعروفة أن تُدوَّن بأثر رجعيّ.²

7. أمثلة فعليّة على ADR

نعرض نصّين كاملين لـADR بصيغتهما الفعليّة، حول موضوعين شائعين في تطبيقات Windows الصغيرة للأعمال (المحتوى أمثلة معمَّمة).

الأوّل قرار اختيار قاعدة البيانات، وهو مثال كلاسيكيّ للاختيار التقنيّ.

# ADR-0002: تخزين بيانات الأعمال يكون في SQLite

## الحالة

معتمَد (2026-07-17)

## السياق

هذا النظام تطبيق سطح مكتب لإدارة المخزون في موقع واحد. عدد المستخدمين 2-3 أشخاص،
لكن من الناحية التشغيلية يُثبَّت على جهاز الحاسوب الرئيسي في مكتب الإدارة فقط،
ويُستخدَم بالتناوب (مستخدم واحد في الوقت نفسه). لا يوجد لدى العميل موظّف
يستطيع تشغيل خادم قاعدة بيانات، ولا ميزانية لإدخال جهاز خادم.
حجم البيانات المتوقَّع بعد 10 سنوات من التشغيل بضع مئات من الميغابايتات.
دُرست كخيارات SQL Server Express و SQLite وملفّ Access (.accdb).
استُبعِد SQL Server Express لأنّ العميل لا يملك جهة قادرة على بناء الخادم
والتحقّق من عمله باستمرار بعد كلّ تحديث Windows. واستُبعِد Access
مراعاةً لمخاطر التلف عند التحديث المتزامن وقابلية الترحيل مستقبلاً.

## القرار

يُعتمَد SQLite لتخزين البيانات. لا يوضَع ملفّ قاعدة البيانات في مجلّد مشترك،
بل محليّاً على الجهاز الرئيسي. تُنشَأ نسخة احتياطية يوميّة بلقطة (snapshot)
عبر VACUUM INTO وتُحفَظ في NAS (نسخ الملفّ الحيّ أثناء التشغيل مباشرةً غير
مسموح لأنّه يُنتج نسخة احتياطية تالفة بسبب فقدان أجزاء من ملفّ WAL أو تعارض الكتابة).

## النتيجة

- نقطة جيدة: لا حاجة لبناء خادم قاعدة بيانات وصيانته. تكتمل النسخة الاحتياطية بجملة SQL واحدة
- نقطة جيدة: يمكن تضمين بيئة التشغيل (runtime) في توزيع التطبيق، فيصبح التثبيت بسيطاً
- نقطة سلبية: الكتابة تُقفَل على مستوى قاعدة البيانات بأكملها، فلا يمكن التوسّع لمواقع متعدّدة أو عدد كبير من المستخدمين
- نقطة سلبية: عند الانتقال مستقبلاً إلى قاعدة بيانات خادم، يلزم ترحيل البيانات وتعديل طبقة الاتّصال
- سيُعاد النظر في هذا القرار عندما يصبح الاستخدام المتزامن من عدّة أجهزة ضروريّاً (عندئذٍ سيتحوّل التكوين إلى قاعدة بيانات خادم أو عبر API)

المثال الثاني حالة التراجع عن قرار سابق. لاحظ أيضاً طريقة استخدام Superseded.

# ADR-0007: إخراج التقارير إلى Excel يكون بتوليد مكتبة لا بتكامل COM

## الحالة

معتمَد (2026-07-17) ── يستبدل ADR-0003 (اعتماد أتمتة COM)

## السياق

هناك متطلّب لإخراج فواتير التسليم والتجميع الشهريّ كملفّات Excel.
نُفِّذ ذلك في البداية عبر أتمتة COM لـExcel وفق ADR-0003، لكن حدثت
مراراً حالات بقيت فيها عملية Excel معلَّقة أثناء التشغيل الليليّ غير
المراقَب (batch)، ما أوقف المعالجة، كما أصبحت ضرورة ترخيص Office
على جهاز التشغيل مشكلة متكرّرة عند كلّ تحديث للأجهزة.
دُرست كخيارات: الاستمرار في تكامل COM (مع إضافة مراقبة للعملية) /
التحوّل إلى مكتبة تولّد صيغة Open XML مباشرةً /
تحويل التقارير إلى PDF (تغيير في المواصفات). استُبعِد التحويل إلى PDF
لأنّ الطرف المتعامل يفترض إمكان الإضافة اليدويّة في Excel.

## القرار

يُستبدَل أسلوب إخراج التقارير بتوليد ملفّات .xlsx مباشرةً عبر مكتبة.
لا اعتماد على تطبيق Excel نفسه. تُدرَج التنسيقات كملفّات .xlsx نموذجية
(template) ضمن المستودع، ويُنشَأ الملفّ بتعبئة الخلايا.

## النتيجة

- نقطة جيدة: لم تعد بيئة التشغيل بحاجة إلى Excel، فيصبح التشغيل غير المراقَب مستقرّاً
- نقطة جيدة: تختفي مشكلة تعليق العمليّة بنيويّاً
- نقطة سلبية: لا يمكن استخدام كلّ ميزات Excel، فيلزم تبسيط بعض تنسيقات التقارير القائمة
- نقطة سلبية: تحويل التقارير القائمة إلى قوالب (templates) يتطلّب جهد تعديل
- تحوّلت حالة ADR-0003 إلى Superseded مع إضافة إشارة إلى هذه ADR

بمجرّد قراءة هذين المثالين، يمكن الإجابة عن الأسئلة التي تظهر حتماً عند التسليم، مثل «لماذا لا توجد قاعدة بيانات خادم في هذا النظام؟» و«لماذا توجد آثار لتشغيل Excel في شيفرة التقارير؟». الإجمالي نحو 1,500 حرف، ولا يستغرق كتابتهما ساعة كاملة.

8. الخلاصة

• ما يُفقَد فيُصعِّب الصيانة والتسليم ليس What بل Why. القرار غير المُدوَّن يُنسى، ويجلب إعادة فتح النقاش وتعديلات تخالف النيّة.²
• ADR صيغة توثيق خفيفة: قرار واحد = ملفّ واحد، بخمسة عناصر، وضمن صفحة أو صفحتين. يمكن استخدامها في التطوير الصغير كما هي بصيغة Nygard الأصليّة.¹
• لا تُكتَب إلّا القرارات «التي يصعب تغييرها» أو «كان لها خيارات» أو «حسمها قيد ما». تُترَك الاتّفاقيّات والتنسيق للأتمتة، ولا تدخل في نطاق ADR.²
• مكان الحفظ docs/adr/، والمراجعة مع طلب السحب. لا تُستبدَل القرارات كتابةً فوقها، بل بـSuperseded، فيبقى التاريخ ثابتاً.¹²
• في التطوير التعاقديّ، تصبح ADR مُخرَج تسليم ذا قيمة للجهة الطالبة أيضاً، كمادّة شرح عند القبول ومادّة تسليم عند تبديل المورِّد.
• 15 إلى 30 دقيقة لكلّ سجلّ. ابدأ بكتابة سجلّ واحد من قرار التصميم القادم، وإن كان النظام قائماً، ابدأ بكتابة بضعة سجلّات بأثر رجعيّ للقرارات الرئيسيّة المعروفة فقط.

مقالات ذات صلة

• كيف يُبرَم عقد التطوير التعاقديّ والتشغيل والصيانة - التمييز بين شبه التفويض والمقاولة وفق «العقود والصفقات النموذجيّة» لـ IPA
• العمل الصحيح بعقد شبه التفويض لتجنّب التعاقد المقنَّع
• ما ينبغي ترتيبه قبل طلب تطوير تطبيق Windows بالتعهيد الخارجيّ أو التعاقد
• أساسيّات إعداد دليل Word - أمثلة سيّئة وحلول للتحسين

مجالات الاستشارة ذات الصلة

تتعامل شركة كومورا سوفت ذ.م.م. مع دعم إدخال ADR ضمن مراجعة التصميم، وجرد قرارات التصميم في الأنظمة القائمة وتوثيقها، وبناء نظام صيانة يستعدّ للتسليم وتبديل الموردين.

• الاستشارة التقنية ومراجعة التصميم
• تطوير تطبيقات Windows
• تعديل وصيانة برامج Windows القائمة
• التواصل معنا

المراجع

مقالات ذات صلة

أحدث المقالات التي تشترك في نفس الوسوم. عمّق فهمك بمواضيع مرتبطة.

الأسئلة الشائعة

أسئلة شائعة حول موضوع هذه المقالة.

ما هو ADR (Architecture Decision Record)؟

هو وثيقة تسجّل قراراً واحداً يتعلّق ببنية البرمجيات في ملفّ واحد، وفق قالب قصير ثابت هو «العنوان / الحالة / السياق / القرار / النتيجة». اقترح Michael Nygard هذه الصيغة الخفيفة عام 2011، وتقتصر عادةً على صفحة أو صفحتين لكلّ سجلّ، وتُحفَظ كـMarkdown يُودَع (commit) في المستودع نفسه الذي يحوي الشيفرة. وخلافاً لوثيقة التصميم الشاملة، يتخصّص ADR في توثيق «لماذا اختير هذا الخيار» و«الخيارات التي استُبعِدت».

ماذا يُكتَب في ADR، وماذا لا يلزم كتابته؟

ما ينبغي كتابته هو القرارات التي يصعب تغييرها لاحقاً (كاختيار قاعدة البيانات أو طريقة الاتّصال، أو صيغة التكامل الخارجيّ)، والقرارات المُتّخَذة من بين عدّة خيارات معقولة، والقرارات التي حسمتها قيود مثل الميزانيّة أو الموعد النهائيّ أو الأصول القائمة. أمّا في المقابل، فما يمكن توحيده آليّاً عبر أداة أو اتّفاقيّة، كقواعد التسمية أو إعدادات المنسِّق (formatter)، أو ما يسهل تغييره ويكفي فيه قراءة الشيفرة، فلا حاجة لكتابته. عند التردّد، المعيار هو: «هل سيرغب أنا بعد سنة في أن أسأل: لماذا؟».

إذا رغبت في تغيير قرار، هل يجوز تعديل ADR القديم؟

لا تُعدَّل، بل تُضاف ADR جديدة تحلّ محلّها. تُغيَّر حالة ADR القديمة إلى Superseded (مُستبدَلة) مع إضافة إشارة إلى ADR الجديدة، ويبقى نصّها كما هو. توصي إرشادات Microsoft أيضاً بمعاملة ADR كسجلّ يُضاف إليه فقط (append-only)، وبعدم تعديل السجلّات المعتمَدة لاحقاً. وبهذا يتحوّل تاريخ «متى ولماذا تغيّرت السياسة» نفسه إلى مادّة تسليم وتسلّم.

إذا كانت هناك وثيقة تصميم، أفلا يكون ADR غير ضروريّ؟

الدوران مختلفان. تُبيّن وثيقة التصميم «ما هي البنية الحاليّة (What)»، لكنّها عادةً لا تحفظ «لماذا اختيرت هذه البنية وما الذي استُبعِد (Why)». كما أنّ وثيقة التصميم الشاملة يتوقّف تحديثها بسهولة، وتميل إلى الانحراف عن الشيفرة بعد سنوات. أمّا ADR فتُضيف بضع مئات من الحروف مع كلّ قرار فقط، فلا يتوقّف تحديثها بسهولة، وحتّى إذا قدُمت وثيقة التصميم، تبقى «أسباب القرارات» وحدها حيّة. في التطوير الصغير، من الواقعيّ تخفيف وثيقة التصميم التفصيليّة واستخدام ADR بالتوازي معها.

الملف الشخصي للمؤلف

صفحة الملف الشخصي لمؤلف المقالة.

غو كومورا

مؤسّس شركة كومورا سوفت ذ.م.م.

يركّز على تطوير برامج ويندوز، والاستشارات التقنية، والتحقيق في الأخطاء، ويتميّز في المشاريع التي تبقى فيها الأصول القديمة ناشطة، وفي تشخيص الأعطال التي يصعب تحديد سببها.