تقرأ الوكلات مستودع الكود الخاص بك، وهذا يغطي معظم ما تحتاجه — لكن ليس القرارات التي توجد في أذهان الأشخاص، أو في ويكي، أو في محادثة منذ عامين.
سياق المشروع هنا تضيف بقية التفاصيل.
ما يمكن لـ Coroid استنتاجه بشكل مستقل
من مستودع الكود وحده، تستطيع الوكلات رؤية ما يلي:
- اللغات والأطر والمكتبات المستخدمة
- طريقة بناء المشروع واختباره وتشغيله
- الأنماط الموجودة — كيف يتم التعامل مع الأخطاء، وكيف تُنظم الوحدات، وكيف تُسمى العناصر
- ما يعتمد على ماذا
لا حاجة لتوثيق أي من هذه الأمور؛ فإعادة صياغتها تمثل جهدًا مهدورًا وقد تتعارض مع الكود، الذي يُعد المصدر الأكثر دقة على أي حال.
ما لا يمكنها استنتاجه
يُظهر الكود ما قمتَ بفعله، وليس لماذا:
- سبب اختيار مكتبة معينة بدلاً من بديل واضح، والذي لا يزال ساريًا حتى الآن
- نمط يبدو وكأنه تكرار لكنه تم تصميمه عمدًا كفاصل بين أجزاء المشروع
- وحدة لا ينبغي لمسها دون التحدث مع فريق محدد
- اتفاقيات تم الاتفاق عليها لكن لم يتم تطبيقها بعد في أي مكان
- قيود خارج نطاق الكود — مثل الامتثال، والعقود، أو عملية ترحيل جارية
هذا هو ما يندرج ضمن سياق المشروع. والاختبار بسيط: هل يمكن لشخص يقرأ مستودع الكود فقط أن يستنتج ذلك؟ إذا كان الجواب نعم، فتجاهله. وإذا كان لا، فاكتبه.
إضافة سياق
الصق الوثائق والسياسات والمراجع ضمن قسم "سياق" الخاص بالمشروع. سياق هناك. تعمل ملاحظات الهندسة المعمارية، وسجلات القرارات، وأدلة الأسلوب، وعقود API جميعها بشكل جيد.
السياق الجيد يكون مختصرًا ودقيقًا؛ فدليل التوجيه الذي يتكون من 40 صفحة والمكتوب للبشر يحتوي في الغالب على سرد، بينما الفقرات الثلاث التي توضح القيود الحقيقية هي ما يهم. استخرج تلك الفقرات.
سياق كل مهمة على حدة
السياق المرتبط بالمشروع ينطبق على كل شيء؛ أما بالنسبة لما يخص جزءًا معينًا من العمل — مثل تذكرة، أو وثيقة تصميم، أو تقرير عميل — فالأفضل ربطه بالمهمة نفسها.
احتفظ بسياق المشروع للأمور الثابتة؛ فملاحظة مرتبطة بمهمة معينة في سياق المشروع ستتحول إلى ضجيج في كل مهمة مستقبلية.
الحفاظ على دقة السياق
السياق الذي فقد صلاحيته أسوأ من عدم وجود سياق، لأن الوكلات تعتبره مصدرًا موثوقًا؛ وعند تغيير أي اتفاقية، يجب تحديث السياق في نفس التغيير الذي يطال الكود.
إذا وجدت نفسك تصحح نفس الشيء مرارًا وتكرارًا في تعليقات إعادة العمل، فهذا مؤشر على وجود نقص في السياق — أو أن هناك خطأ فيه.