ملف الـ README الخاص بي قال 80 أداة. الكود الخاص بي كان يحتوي على 96. لم يلاحظ أحد ذلك لأسابيع.
أدير مشروعاً مفتوح المصدر. يستخدم أتمتة المتصفح لوكلاء الذكاء الاصطناعي (AI agents).
ذكر ملف الـ README الخاص بي أن المشروع يحتوي على 80 أداة. وضعت هذا الرقم في الشعار (tagline)، وفي شريط التنقل، وفي نصوص وسائل التواصل الاجتماعي.
في الأسبوع الماضي، أجريت عملية تدقيق. قارنت ملف الـ README بالكود الفعلي الخاص بي.
سجل الكود 96 أداة.
كان لدي ثلاث حقائق مختلفة في ملف واحد:
- الرقم التسويقي: 80
- القائمة الموثقة: 83
- الكود الفعلي: 96
ثلاث عشرة أداة لم تكن موثقة على الإطلاق. لم يكن المستخدمون يعلمون بوجودها.
الجزء الأكثر خطورة كان الفجوة. أربع من تلك الأدوات غير الموثقة كانت أدوات نظام رفيعة المستوى (high-level system tools). كانت تستخدم أحداثاً على مستوى نظام التشغيل (OS-level events) للتحكم في لوحة المفاتيح والفأرة. هذا هو الجزء الأكثر قوة وحساسية في مشروعي.
لقد علمني هذا درساً قاسياً حول "انحراف التوثيق" (documentation drift).
الانحراف ليس عشوائياً، بل هو منحاز. أنت توثق الأشياء السهلة والمملة، وتنسى توثيق الأدوات الجديدة أو القوية أو الحساسة التي تطلقها على عجل.
إذا كنت تريد العثور على الجزء الأكثر خطورة في المشروع، فلا تقرأ الوثائق. انظر إلى الفجوة بين الوثائق والكود.
حاولت تصحيح الرقم، وكان ذلك خطأً. تصحيح الرقم يعالج العرض فقط.
المشكلة تكمن في الصيانة اليدوية. إذا قام إنسان بكتابة حقيقة ما، فإن هذه الحقيقة ستصبح خاطئة في نهاية المطاف.
الحل الحقيقي الوحيد هو جعل من المستحيل كتابة الرقم بشكل خاطئ.
يجب عليك استخلاص الحقائق من "مصدر الحقيقة" (source of truth).
كان مشروعي يمتلك حلاً بالفعل: اختبار الدخان (smoke test). يسأل الاختبار الخادم عن عدد الأدوات التي لديه ويتحقق من العدد. هو لا يستخدم رقماً ثابتاً (hardcoded number). لا يمكن للاختبار أن ينحرف أبداً لأنه لا يخزن رقماً ثابتاً.
توقف عن محاولة أن تكون أكثر انضباطاً في كتابتك. الانضباط يفشل. بدلاً من ذلك، قم بأتمتة حقائقك:
- قم بتوليد الأعداد باستخدام سكربت (script) أثناء وقت البناء (build time).
- قم بتوليد قوائم الأدوات مباشرة من سجل الكود الخاص بك (code registry).
- استخدم البشر فقط لكتابة النثر والشروحات.
إذا كانت الحقيقة قابلة للاستخلاص، فلا تكتبها يدوياً. إنها مجرد انحراف ينتظر الحدوث.
أجرِ هذا التدقيق على مشروعك الخاص اليوم:
- احسب العناصر الحقيقية في الكود الخاص بك.
- احسب ما تدعيه وثائقك.
- إذا اختلفا، فاكتشف ما يوجد في تلك الفجوة.
العناصر الموجودة في الفجوة هي عادةً الأجزاء الأكثر أهمية في مشروعك.
مجتمع تعليمي اختياري: https://t.me/GyaanSetuAi