ثقافة مراجعة الشيفرة وأفضل ممارسات PR

مراجعة الكود ليست وسيلة لفرض الحواجز، بل هي الطريقة التي تتعلم بها الفرق معًا، وتنقل بها مسؤولية الملكية، وتحافظ على جودة عالية. ثقافة المراجعة الجيدة ترفع مستوى الفريق بأكمله، أما السيئة فتسبب الاختناقات والاستياء.

1) اجعله صغيرًا (أقل من 400 سطر إن أمكن). 2) اكتب وصفًا واضحًا: لماذا، وماذا، وكيفية الاختبار. 3) أضف رابط التذكرة. 4) أضف لقطات شاشة أو مقاطع فيديو لتغييرات واجهة المستخدم. 5) راجع diff بنفسك قبل طلب المراجعين.

استخدم البادئات التقليدية نفسها المستخدمة في commits: feat: add user profile page، وfix: handle 404 in fetch wrapper، وrefactor: extract Avatar component. تنشئ فرق كثيرة changelogs اعتمادًا عليها.

تستخدم معظم الفرق قالبًا لـ PR — ثبّته في .github/pull_request_template.md.

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

نادرًا ما تخضع PR مكوّنة من 2000 سطر لمراجعة دقيقة. قسّمها إلى: 1) إعادة هيكلة (من دون تغيير السلوك)، 2) سلوك جديد، 3) تحسينات على واجهة المستخدم. سيكون من الأسهل مراجعة كل جزء والتراجع عنه.

صُغ ملاحظاتك على شكل أسئلة، لا أوامر: «ما رأيك في استخراج هذا إلى hook؟» أفضل من «استخرج هذا». ميّز بين ما يجب إصلاحه وما يُستحسن تحسينه. استخدم البادئات: nit:، وquestion:، وblocker:.

عبارة «هذا مربك» لا تخبر الكاتب بشيء. أما عبارة «اضطررت إلى قراءة هذا ثلاث مرات لفهم الخروج المبكر — هل يمكننا استخراج guard clause؟» فتعطيه شيئًا واضحًا يمكنه العمل عليه.

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

يتولى Prettier تنسيق الكود، ويتولى ESLint قواعد الأسلوب. لا تهدر دورات المراجعة في نقاش tabs-vs-spaces. إذا تكررت قاعدة أسلوبية باستمرار، فطبّقها في linter.

الاختبارات كود أيضًا. تأكد من وجود اختبارات للكود الجديد. وتحقق من أن الاختبارات تختبر الشيء الصحيح فعلًا — فكثير من الاختبارات تنجح حتى عند وجود خلل لأنها تتحقق من الشيء الخطأ.

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

أجرِ المراجعة خلال يوم عمل واحد. تفقد PR القديمة سياقها — فقد يكون الكاتب انتقل إلى عمل آخر، وقد يحتاج الفرع إلى إعادة الأساس. أما PR الكبيرة التي تبقى أسبوعًا فتنتهي دائمًا بعمليات دمج شاقة.

تتيح ميزة الاقتراحات في GitHub للكاتب قبول الإصلاح بنقرة واحدة. وهذا أسرع بكثير من كتابة «غيّر هذا السطر إلى X» ضمن نص عادي.

وافق عندما يكون الكود صحيحًا، وتنجح الاختبارات، وتفهم التغيير، ويكون الدمج آمنًا. تعني الموافقة أنك تشارك في تحمل مسؤولية النتيجة. لا تمنح موافقة شكلية — إذا لم تقرأ التغيير، فصرّح بذلك.

الكاتب: PR صغيرة وموصوفة جيدًا، مع لقطات شاشة واختبارات. ابدأ بالمراجعة الذاتية. المراجع: ملاحظات بنّاءة قائمة على الأسئلة. ميّز بين ما يمنع الدمج والملاحظات البسيطة. أثنِ على الجوانب الجيدة. تجاوز الأسلوب — ودَع الأدوات تتولاه. أجرِ المراجعة خلال يوم. لا توافق إلا عندما تفهم التغيير. توحّد قوالب PR العملية. المراجعات تعاون، وليست وسيلة لفرض الحواجز.