تقدير المشروع
← كل المقالات

خرافة الشيفرة الموثِّقة لنفسها

إذا كانت شيفرتك توثّق نفسها، فهل يمكنك الاستغناء عن كتابة التعليقات؟ ليس تمامًا – وإليكم التفسير.

3 دقائق قراءة
GitGithubالشيفرة النظيفةالتوثيقPull Request

أو بعبارة أدق: هذا هدف ممتاز يمكن بلوغه أحيانًا، لكنه لا يعفيك من التعليق على شيفرتك. فكل موضع غير بديهي يستحق تعليقًا – وهذه المواضع أكثر مما تتوقع! فبصفتنا كتّاب الشيفرة، همّنا الأول هو راحة من يقرؤها: نريد قبل كل شيء أن يتمكن الآخرون، أو نحن أنفسنا في المستقبل، من فهمها.

والمبادئ التي تقوم عليها الشيفرة الموثِّقة لنفسها سليمة بطبيعة الحال (وهي مفيدة لأسباب أخرى أيضًا): إبقاء الدوال/الدوال الأعضاء (methods) صغيرة، وتخصيص نصف يوم العمل لاختيار الأسماء المناسبة، وتصميم حدود تجريد ملائمة، وكتابة اختبارات تتحقق من سلوك الشيفرة وتعمل في الوقت نفسه كوثائق مُصرَّفة.

ومع ذلك، ستبقى هناك دائمًا مقاطع من الشيفرة تجعل القرّاء يحكّون رؤوسهم، ويتأملون كيف يعبّرون للكاتب عن «امتنانهم» على أفضل وجه. (وقد تكون هذه المقاطع تحديدًا هي التي يجب كتابتها يدويًا بدلًا من توليدها بواسطة ChatGPT.)

قد يكون هذا المقطع مثلًا تكاملًا مع خدمة خارجية غريبة الأطوار: صِف هذه الغرابة. أو قاعدة عمل تبدو بعد تحويلها إلى شيفرة كأنها معالجة غريبة للبتات، لكن لا بد فعلًا من كتابتها بهذه الطريقة لأنها تقع على المسار الحرج: اشرح «السبب». لغات البرمجة لدينا معبّرة جدًا، لكن لها حدودًا – وعندما تبلغها، فلا تتردد في اللجوء إلى تعليق.

قد يبدو كل هذا بديهيًا، لكن كيف نكتشف المقاطع الأخرى التي تحتاج إلى تعليق؟ كتقريب أول، اعتمد على الحس السليم (فتوثيق Person getPerson() بعبارة gets the person مثلًا لا ينبغي أن يجتاز هذا المرشِّح). ومع ذلك، قد نكون متفائلين أكثر من اللازم بشأن مدى وضوح تجريدنا الجديد اللامع.

لذلك، وكتقريب ثانٍ، من المفيد النظر في تعليقات مراجعة الشيفرة، مثل نقاشات طلبات الدمج (PR) / (merge request). واطلب من مراجعي الشيفرة أن يشيروا إلى الأماكن التي كان من الصعب فيها تتبّع سير الشيفرة.

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

النقاشات في طلبات الدمج والمشكلات (issues) مفيدة وتساعد على تقصير حلقة التغذية الراجعة. استفد من المعلومات التي تحتويها، ولا تدعها تموت! ولا تخشَ تكرارها: فمن يحالفه الحظ لتعديل الشيفرة في المستقبل سيقرأ الشيفرة وحدها – ولن يتعقّب سجل دمج الطلبات كله والنقاشات المرتبطة به. إلا إذا غضب حقًا وأصابه اليأس – لكن لنحاول منع ذلك.

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

«لكن مهلًا!» قد تعترض، «التوثيق يصبح قديمًا!». صحيح، والتعليقات قد تنحرف عن الشيفرة التي تصفها. هذه بالتأكيد مشكلة. لكنها تصح بشكل خاص عندما يكون التوثيق بعيدًا عمّا يوثّقه. التعليقات في موضع أفضل: يمكنك وضعها داخل الشيفرة، بجوار المنطق مباشرة، مما يقلل خطر تقادمها.

وهناك حجة أخرى لصالح تعليقات الشيفرة: حين يتعلق الأمر بالشيفرة المصدرية نفسها، ينبغي أن تكون الشيفرة المصدرية المصدر المركزي للحقيقة. ذكرنا سابقًا أن المعلومات المتناثرة في عدة أماكن – تعليقات طلبات الدمج، ووصف المشكلات، والشيفرة المصدرية – يصعب التنقل بينها. وعلاوة على ذلك، فهي خاضعة جزئيًا للارتباط بمزوّد بعينه (vendor lock-in). Git نظام تحكم بالإصدارات موزَّع، لذا يملك الجميع نسخة احتياطية كاملة ومحدّثة بانتظام – لكن فقط للمعلومات التي تعيش فعلًا في git.

تحتفظ طلبات الدمج والمشكلات وعقولنا بالكثير من المعلومات: لا تتركها هناك! ولا تدعها تموت! وللتلخيص:

  • حتى أنظف قواعد الشيفرة تحتاج إلى تعليقات
  • تعامل مع تعليقات مراجعة الشيفرة كإشارات إلى مواضع تحتاج إلى إعادة هيكلة أو تعليق
  • دوّن «السبب» مستفيدًا من سياق المشكلة/تقرير الخلل الذي تعمل عليه
  • انقل أي شيء مهم من المشكلة أو من نقاش PR/MR إلى قاعدة الشيفرة – عبر التسمية أو بنية الشيفرة أو التعليقات
  • اجعل الشيفرة المصدرية المصدر المركزي للحقيقة بشأن الشيفرة المصدرية.