مراجعة الكود — ما هي، كيف تعمل مراجعة الكود والتحقق من PR

ما هي مراجعة الكود

مراجعة الكود هي فحص منهجي للكود من قبل الزملاء قبل دمجه. في سياق Git،这意味着: يقوم المطور بإنشاء طلب سحب مع تغييرات، ويعين مراجعين، ويدرسون الفرق، ويتركون تعليقات， ويصدرون حكمًا. يمكن للمراجع طلب تغييرات، أو الموافقة على PR، أو ترك تعليق عام.

تحقق مراجعة الكود خمسة أهداف: تحسين جودة الكود (اكتشاف العيوب قبل وصولها إلى الإنتاج)، ونشر المعرفة (يتعلم المراجع عن الأساليب الجديدة， ويتلقى المؤلف ردود فعل)， وضمان المعايير (التحقق من الامتثال لأسلوب الكود والقرارات المعمارية)， وتقليل عامل الحافلة (أكثر من مطور واحد يعرف الكود)， وبناء ثقافة المسؤولية (يكتب المؤلف بدقة أكبر مع علمه أنه سيتم مراجعة الكود).

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

ما الذي يجب التحقق منه في مراجعة الكود

يجب أن تكون مراجعة الكود منهجية، وليست فوضوية. يتحقق المراجعون ذوو الخبرة من الكود بترتيب محدد: أولاً الهندسة والمنطق، ثم الاختبارات، ثم الأمان والأداء، وفقط في النهاية — الأسلوب والتسمية. يضمن هذا الترتيب ملاحظة المشكلات الحرجة قبل أن يتعب المراجع.

الهندسة والمنطق: هل يحل الكود المهمة، هل هناك تجريدات مفرطة، هل تم اتباع مبادئ SOLID و DRY. الكود المعقد الذي يصعب فهمه من القراءة الأولى هو إشارة إلى أن إعادة الهيكلة مطلوبة. يجب على المراجع التأكد من أن الكود يفعل بالضبط ما تحدده المهمة وليس له آثار جانبية خارج نطاق مسؤوليته.

الاختبارات: هل تغطي الاختبارات الجديدة جميع السيناريوهات — الإيجابية والسلبية وحالات الحدود. هل تجتاز الاختبارات الحالية بعد التغييرات. هل هناك اختبارات غير مستقرة تفشل بشكل غير متناسق. الأمان: غياب حقن SQL، XSS، تسرب البيانات الحساسة من خلال السجلات أو استجابات API. الأداء: كفاءة الخوارزميات، الاستعلامات المفرطة لقاعدة البيانات، تسرب الموارد.

• الهندسة — صحة الحل، الامتثال لـ SOLID، غياب الإفراط في الهندسة.
• المنطق — معالجة جميع السيناريوهات، بما في ذلك الأخطاء والحالات الحدودية.
• الاختبارات — تغطية التغييرات الجديدة، عدم كسر الاختبارات الحالية.
• الأمان — الحقن، XSS، CSRF، تسرب البيانات من خلال السجلات.
• الأداء — تعقيد الخوارزميات، استعلامات N+1، تسرب الذاكرة.

حجم المراجعة: لماذا 400 سطر هو الحد الأقصى

الحد الأقصى لحجم PR هو المقياس الأكثر أهمية لفعالية مراجعة الكود. أظهرت دراسة من Cisco (2015) والتجارب اللاحقة من SmartBear و Google أنه عندما يتجاوز حجم المراجعة 400 سطر، تنخفض قدرة المراجع على اكتشاف العيوب بشكل حاد. إذا تجاوز PR 400 سطر， يتم اكتشاف العيوب باحتمالية لا تتجاوز العشوائية.

الحجم الأمثل: 200–400 سطر لكل PR. يمكن مراجعة هذا الحجم في 30–60 دقيقة مع الحفاظ على التركيز. توصي Google بما لا يزيد عن 200 سطر لكل جولة مراجعة بتركيز كامل. إذا كانت التغييرات أكبر، يجب تقسيم المهمة إلى عدة PR متسلسلة， كل منها يقدم تغييرًا مكتملًا منطقيًا.

وقت المراجعة: خلال 24 ساعة من إنشاء PR. إذا استغرقت المراجعة عدة أيام， يفقد سياق المهمة， ويضطر المؤلف إلى قضاء الوقت في استعادة السياق عند الرد على التعليقات. تضع الفرق ذات الثقافة القوية لمراجعة الكود اتفاقيات مستوى الخدمة على المراجعة: على سبيل المثال， 4 ساعات للتغييرات الحرجة و 24 ساعة للتغييرات العادية.

كيفية كتابة تعليقات مراجعة جيدة

نبرة التعليقات مهمة جدًا لفعالية مراجعة الكود. تعليق مثل «هذا خطأ» يسبب رد فعل دفاعي ولا يقدم معلومات مفيدة للمؤلف. الصياغة الأفضل هي سؤال-اقتراح: «ما رأيك في هذا النهج؟»، «قد يسبب هذا NPE إذا كان user == nil. ربما إضافة guard؟». الأسئلة أقل مواجهة وتحفز النقاش.

يتضمن التعليق الجيد ثلاثة أجزاء: ما هو الخطأ، ولماذا هو مشكلة، وكيفية إصلاحه. مثال: «تستخدم هذه الحلقة O(n²) بسبب contains المتداخلة， مما قد يبطئ مع 10k+ سجل. جرب استبدالها بـ Set للبحث O(1).». هذه الصياغة تحدد المشكلة في نفس الوقت، وتشرح أهميتها， وتقترح حلاً — لا يحتاج المؤلف إلى التخمين.

يدعم GitHub و GitLab الاقتراحات — مقترحات تغيير الكود المضمنة. يمكن للمراجع كتابة: «```suggestion Filter empty strings before processing```» ويمكن للمؤلف تطبيق التغيير بنقرة واحدة. هذا يسرع التصحيحات الصغيرة ويقلل عدد جولات المراجعة. للتغييرات الكبيرة， من الأفضل كتابة تعليق عام بدلاً من تضمين كتل كبيرة في الاقتراح.

# قالب لتعليق مراجعة كود جيد

# سيء: "This code is wrong"
# جيد: "We may lose data on empty response.
#         If response.data == nil, the guard returns nil,
#         and user sees empty screen without error.
#         Maybe add a fallback error message?"

# صيغة اقتراح GitHub:
# ```suggestion
# let result = try? parse(response, fallback: .defaultValue)
# ```

سير عمل مراجعة الكود في الفريق

سير العمل الفعال للمراجعة مبني على أربع مراحل. الأولى — يقوم المؤلف بإعداد PR: يكتب عنوانًا واضحًا (على سبيل المثال، «feat: add password reset screen»)، ويضيف وصفًا للتغييرات، وروابط للمهمة في المتتبع， وتعليمات الاختبار. الثانية — يعين المؤلف المراجعين عبر التعيين التلقائي (بناءً على CODEOWNERS) أو يدويًا.

المرحلة الثالثة — يتحقق المراجع من الكود ويترك تعليقات. الرابعة — يقوم المؤلف بإجراء التصحيحات， والرد على التعليقات， وطلب إعادة المراجعة. تتكرر الدورة حتى الحصول على الموافقة. بعد الموافقة， يقوم المؤلف بالدمج (أو يقوم الروبوت بذلك). تعمل الأتمتة عبر Mergify أو GitHub Auto-merge على تسريع المرحلة النهائية.

عنصر مهم في سير العمل — إدارة PR القديمة. إذا بقي PR دون مراجعة لأكثر من 3 أيام， يتم حظر العملية. الحلول: تدوير المراجعين (إذا كان المعين غير متاح)، الإشعارات عبر Slack/Teams، حد زمني للمراجعة (SLA). في بعض الفرق， يتم إغلاق PR بدون مراجعة لأكثر من 7 أيام تلقائيًا， ويقوم المؤلف بإنشاء PR جديد بعد المزامنة مع main.

• إنشاء PR — عنوان واضح، وصف، روابط للمهمة، لقطات شاشة لتغييرات الواجهة.
• التعيين — التعيين التلقائي عبر CODEOWNERS أو اختيار يدوي لـ 1–2 مراجعين.
• المراجعة — التحقق بالترتيب: الهندسة → المنطق → الاختبارات → الأمان → الأسلوب.
• التصحيحات — يرد المؤلف على جميع التعليقات， ويصلح المشكلات العالقة، ويطلب إعادة المراجعة.
• الدمج — بعد الموافقة و CI أخضر， يقوم المؤلف أو الروبوت بالدمج.

الأخطاء الشائعة في مراجعة الكود

الخطأ الأول — مراجعة سطحية. يمسح المراجع الفرق بسرعة دون التعمق في المنطق ويضغط على موافقة. الأسباب: PR كبير، موعد نهائي， إرهاق. العواقب: تصل الأخطاء إلى الإنتاج. الحل: إذا لم يكن هناك وقت لمراجعة جيدة — اكتب بصدق «لا أستطيع المراجعة اليوم， انقلوها إلى الغد» بدلاً من الموافقة الرسمية.

الخطأ الثاني — النقد المفرط (الانتقاء). يترك المراجع عشرات التعليقات حول أسلوب التنسيق، تسمية المتغيرات， التفاصيل التافهة. هذا يثبط عزيمة المؤلف ويطيل المراجعة. الحل: يجب أن يتحقق دليل الأسلوب والأدوات من الأسلوب تلقائيًا. الإنسان في المراجعة يتحقق من المنطق， الهندسة， والأمان.

الخطأ الثالث — مراجعة بدون أسئلة. إذا كان المراجع ينشر فقط طلبات التغيير والموافقة ولكن لا يطرح أسئلة， فإنه يفوت فرصة تعلم شيء جديد. أفضل مؤشر على صحة مراجعة الكود هو وجود مناقشات يتعلم فيها الطرفان شيئًا جديدًا. إذا كانت المراجعة عبارة عن مونولوج لأحد المشاركين， فإن العملية معطلة.

• مراجعة سطحية — موافقة دون تحليل عميق. الحل: لا تراجع إذا لم يكن لديك وقت.
• الانتقاء — نقد الأسلوب الذي يجب أن يفحصه linter. الحل: أتمتة فحوصات الأسلوب.
• التفضيل الشخصي — «كنت سأكتبه بشكل مختلف». الحل: يجب أن يعمل الكود، لا أن يعجب المراجع.
• التأخير — مراجعة أطول من 24 ساعة. الحل: SLA على المراجعة， التصعيد عند الانتهاك.
• تجاهل السياق — مراجعة الكود دون فهم المهمة. الحل: قراءة وصف PR قبل الفرق.