الدرس 5: كتابة قصة الكود: التعليقات والتوثيق الفعّال

التعليقات ليست بديلاً للكود الواضح، ولكنها ضرورية لتوضيح القصد المعقد، والقرارات المعمارية، ومعالجة الحالات الحدية (edge cases).

مفارقة إحساس التعليق

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

متى يجب التعليق (إحساس جيد)

1. توضيح القصد (السبب): شرح خيار تصميم غير واضح، خاصة تحسينات الأداء أو الحلول البديلة للمكتبات/الأخطاء الخارجية.
2. ملخصات عالية المستوى: توفير Docstring/Javadoc في بداية دالة أو وحدة معقدة لتحديد الغرض منها، المدخلات، المخرجات، والآثار الجانبية.
3. التحذيرات ومهام TODO: تحديد المناطق التي تحتاج إلى اهتمام مستقبلي (TODO: يجب إعادة هيكلة هذا إلى خدمة مخصصة لاحقاً.).

python

تعليق بإحساس جيد: شرح 'السبب' المعماري

تحذير: هذا الحل البديل ضروري لأن واجهة برمجة التطبيقات القديمة (V1) تعيد الوقت

بالتوقيت المحلي، مما ينتهك ممارسة التوقيت العالمي المنسق (UTC) القياسية. يجب إزالته عند تفعيل V2.

timestamp = adjust_for_legacy_tz(response['time'])

متى لا يجب التعليق (إحساس سيئ)

تجنب التعليق على ما هو واضح. هذه التعليقات تزيد فوضى الكود وتضيف ضوضاء.

javascript // إحساس سيئ: تعليق واضح // حلقة تكرارية على قائمة المستخدمين for (let i = 0; i < users.length; i++) { // زيادة العداد بمقدار 1 count++; }

إحساس التوثيق (الخارجي)

تمتد البرمجة الجوهرية الجيدة إلى ما هو أبعد من الملف. تأكد من أن توثيق مستوى الوحدة (ملفات Readmes، وثائق API) سهل العثور عليه واستخدامه. يجب أن يكون المطور قادراً على استنساخ المستودع الخاص بك والبدء دون قراءة عقلك.