كيف تطلب مراجعة كود فعالة — وكيف تراجع كود غيرك

مقدمة

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

أهداف التعلم

• تجهيز الكود قبل طلب المراجعة.
• كتابة طلب مراجعة يوجه انتباه المراجع.
• المراجعة بقائمة أولويات واضحة.
• كتابة تعليقات محددة وبنّاءة.

الجزء الأول: طالب المراجعة

1. راجع نفسك أولاً

قبل إرسال الطلب:

• اقرأ الفرق (diff) كاملاً كأنك المراجع.
• احذف أسطر الطباعة المؤقتة والكود المعلّق.
• شغّل الاختبارات والتدقيق والتنسيق التلقائي.
• قسّم التغيير الكبير إلى طلبات أصغر.

2. اكتب طلباً يوجه المراجع

## الهدف
إضافة تصدير المصاريف إلى CSV (#42).

## ما الذي تغيّر
- دالة `exportCsv` في `src/export.ts`
- زر في صفحة التقارير
- اختبارات لحالة القائمة الفارغة والأحرف العربية

## أين أحتاج رأيك تحديداً
- هل ترميز UTF-8 مع BOM هو الأنسب ليفتح Excel العربية بشكل صحيح؟
- أداء التصدير لأكثر من 50 ألف سطر.

## كيف اختبرت
`npm test` + تجربة يدوية بملف 60 ألف سطر (1.2 ثانية).

قسم «أين أحتاج رأيك» يجعل المراجع يصرف وقته على ما يهم.

3. تقبّل الملاحظات

رد على كل تعليق: نفّذه، أو اشرح سبب اختيارك بأدب، أو اقترح متابعة في طلب لاحق. وإن طال النقاش المكتوب، فمكالمة قصيرة توفر الكثير.

الجزء الثاني: المراجع

4. أولويات المراجعة

راجع بالترتيب، من الأهم إلى الأقل:

1. الصحة: هل يفعل الكود المطلوب؟ الحالات الحدية؟ الأخطاء؟
2. الأمان: المدخلات، الصلاحيات، الأسرار، الحقن.
3. التصميم: هل الحل في المكان المناسب؟ هل يعقّد النظام دون حاجة؟
4. الاختبارات: هل تغطي السلوك الجديد والحالات الحدية؟
5. الوضوح: الأسماء، البنية، التعليقات المفيدة.
6. الأسلوب: اتركه للأدوات الآلية قدر الإمكان (المنسقات والمدققات).

5. تعليقات محددة وبنّاءة

غير مفيد: «هذا خطأ».

مفيد:

إذا كانت items فارغة فستقسم على صفر في السطر 18. ما رأيك أن نعيد null ونعرض «لا توجد بيانات» في الواجهة؟ أضفت مثالاً للاختبار المقترح أدناه.

• اشرح السبب واقترح بديلاً.
• ميّز بين الإلزامي والاختياري: ابدأ الملاحظات الثانوية بـ «اختياري:» أو «ملاحظة جانبية:».
• اسأل بدل أن تفترض: «هل هناك سبب لاستخدام X هنا؟».
• علّق على الكود لا على الشخص، واذكر ما أعجبك أيضاً.

6. السرعة مهمة

المراجعة المتأخرة تعطل الفريق. حاول الرد خلال يوم عمل، ولا تراجع أكثر من نحو 400 سطر في جلسة واحدة؛ الانتباه يقل كثيراً بعدها.

في مجتمع عرب كود

عند طلب مراجعة في المنتدى أو قسم المشاريع:

• ضع رابط المستودع أو الكود المعني فقط، لا المشروع كله.
• حدد اللغة والإطار والسؤال المحدد.
• احذف الأسرار من أي كود تنشره.

تمرين عملي

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

أخطاء شائعة

• طلب مراجعة لتغيير ضخم دون وصف.
• مراجعة الأسلوب وتجاهل الصحة والأمان.
• تعليقات غامضة أو قاسية.
• الموافقة الشكلية دون قراءة حقيقية.
• ترك الطلبات أياماً دون رد.

الخلاصة

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

مصادر مقترحة

• دليل Google للهندسة: «Code Review Developer Guide».
• conventionalcomments.org لصياغة التعليقات.
• كتاب Software Engineering at Google (فصل مراجعة الكود).