Git و GitHub

أفضل ممارسات مراجعة الكود

13 دقيقة الدرس 27 من 35

أفضل ممارسات مراجعة الكود

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

لماذا تهم مراجعات الكود

فوائد مراجعات الكود:

✓ اكتشاف الأخطاء مبكراً: العثور على المشكلات قبل وصولها إلى الإنتاج
✓ تحسين جودة الكود: ضمان المعايير وأفضل الممارسات
✓ مشاركة المعرفة: يتعلم الفريق من بعضه البعض
✓ الاتساق: الحفاظ على أنماط وأسلوب قاعدة الكود
✓ التوثيق: تصبح مناقشات PR توثيقاً
✓ الإرشاد: يتعلم المطورون المبتدئون من الكبار
✓ الملكية الجماعية: يتشارك الفريق المسؤولية عن الكود

تظهر الأبحاث: تكتشف مراجعات الكود 60-90% من العيوب قبل الإنتاج، مما يجعلها أكثر فعالية من حيث التكلفة من العثور على الأخطاء في الإنتاج.

ما الذي تبحث عنه عند المراجعة

قائمة مراجعة شاملة لكود:

1. الوظيفة
   ☐ هل يفعل الكود ما من المفترض أن يفعله؟
   ☐ هل يتم التعامل مع الحالات الحدية؟
   ☐ هل يتم التعامل مع حالات الخطأ بشكل صحيح؟
   ☐ هل المنطق صحيح وفعال؟

2. التصميم والبنية
   ☐ هل الكود في المكان الصحيح؟
   ☐ هل يتبع الأنماط الموجودة؟
   ☐ هل يمكن صيانته وتوسيعه؟
   ☐ هل المسؤوليات مفصولة بشكل صحيح؟

3. جودة الكود
   ☐ هل الكود قابل للقراءة وواضح؟
   ☐ هل أسماء المتغيرات/الوظائف وصفية؟
   ☐ هل هناك تعقيد غير ضروري؟
   ☐ هل الكود مكرر بشكل غير ضروري؟

4. الاختبار
   ☐ هل هناك اختبارات كافية؟
   ☐ هل تغطي الاختبارات الحالات الحدية؟
   ☐ هل الاختبارات قابلة للقراءة والصيانة؟
   ☐ هل تجتاز جميع الاختبارات؟

5. الأمان
   ☐ هل هناك ثغرات حقن SQL؟
   ☐ هل يتم التحقق من صحة مدخلات المستخدم بشكل صحيح؟
   ☐ هل الأسرار محمية بشكل صحيح؟
   ☐ هل المصادقة/التفويض صحيحة؟

6. الأداء
   ☐ هل هناك مشاكل استعلام N+1؟
   ☐ هل العمليات المكلفة محسّنة؟
   ☐ هل يتم استخدام التخزين المؤقت بشكل مناسب؟
   ☐ هل هناك تسريبات للذاكرة؟

7. التوثيق
   ☐ هل الأجزاء المعقدة معلّقة؟
   ☐ هل وصف PR واضح؟
   ☐ هل التغييرات الكسرية موثقة؟
   ☐ هل التوثيق محدّث؟

استخدام ميزات المراجعة في GitHub

توفر GitHub أدوات قوية لمراجعات الكود الفعالة:

1. أنواع التعليقات:

# تعليق سطر واحد
- انقر على رقم السطر، أضف تعليق
- استخدم لمشكلات السطر المحددة

# تعليق متعدد الأسطر
- انقر واسحب أرقام الأسطر
- استخدم لمراجعة كتل الكود

# تعليق عام
- استخدم علامة تبويب محادثة PR
- استخدم للملاحظات العامة

# اقتراح
- انقر على أيقونة "إدراج اقتراح"
- يقترح المراجع تغيير الكود بالضبط
- يمكن للمؤلف التزام الاقتراح مباشرة

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

كيفية توصيل الملاحظات مهمة بقدر أهمية ما تقوله:

❌ تعليق سيء:
"هذا خطأ."

✅ تعليق جيد:
"قد يتسبب هذا في استثناء مؤشر فارغ عندما لا يكون المستخدم مصادقاً.
فكر في إضافة فحص:

if (!auth()->check()) {
    return redirect()->route('login');
}

ما رأيك؟"

أفضل ممارسة: استخدم "صيغة السؤال" عندما يكون ذلك ممكناً. بدلاً من "هذا خطأ"، اسأل "هل يمكن أن يتسبب هذا في مشكلة إذا حدث X؟"

فن تقديم الملاحظات البناءة

1. كن لطيفاً ومحترماً
   ❌ "هذا الكود رهيب"
   ✅ "أعتقد أن يمكننا تحسين هذا بـ..."

2. ركز على الكود، وليس الأشخاص
   ❌ "لم تتعامل مع الأخطاء"
   ✅ "هذه الوظيفة لا تتعامل مع حالة الخطأ"

3. اشرح "لماذا"
   ❌ "لا تستخدم var_dump()"
   ✅ "لنستخدم Log::debug() بدلاً من var_dump() حتى لا
       نكشف البيانات عن طريق الخطأ في الإنتاج"

4. قدم الحلول، وليس المشاكل فقط
   ❌ "هذا لن يتوسع"
   ✅ "قد يتسبب هذا في مشاكل الأداء مع مجموعات البيانات الكبيرة.
       فكر في استخدام الترقيم أو التحميل المسبق"

5. استخدم لغة إيجابية
   ❌ "نسيت أن..."
   ✅ "لنضيف أيضاً..."

6. امدح العمل الجيد
   ✅ "رائع! هذا التجريد يجعل الكود أكثر نظافة"
   ✅ "رصد رائع لتلك الحالة الحدية"

تذكر: الهدف هو تحسين جودة الكود، وليس إثبات أنك ذكي أو انتقاد المؤلف.

أمثلة على تعليقات المراجعة

مشكلة أمنية:
"⚠️ مخاوف أمنية: هذا الاستعلام عرضة لحقن SQL.
لنستخدم ربط المعاملات:

// بدلاً من:
DB::raw("SELECT * FROM users WHERE id = " . $id)

// استخدم:
DB::table('users')->where('id', $id)->first()
"

مشكلة أداء:
"قد يتسبب هذا في استعلامات N+1. فكر في التحميل المسبق:

// بدلاً من:
foreach ($posts as $post) {
    echo $post->author->name;
}

// استخدم:
$posts = Post::with('author')->get();
"

جودة الكود:
"هذه الوظيفة تقوم بأشياء متعددة. فكر في الاستخراج:

public function processOrder($order) {
    $this->validateOrder($order);
    $this->calculateTotals($order);
    $this->sendConfirmation($order);
}

هذا يجعله أسهل للاختبار والصيانة."

الثناء:
"💯 استخدام ممتاز لنمط المستودع هنا!
هذا يجعل الاختبار أسهل بكثير."

الرد على تعليقات المراجعة

كيفية التعامل مع الملاحظات بشكل احترافي:

1. لا تأخذها على محمل شخصي
   - المراجعات تتعلق بجودة الكود، وليس قيمتك
   - الجميع يحصل على ملاحظات، حتى المطورين الكبار
   - اعتبرها فرصة للتعلم

2. اطلب التوضيح
   "لست متأكداً من أنني أفهم. هل يمكنك التوسع في
   سبب أن هذا النهج أفضل؟"

3. اشرح منطقك
   "اخترت هذا النهج بسبب X و Y و Z.
   ومع ذلك، أنا منفتح على البدائل إذا كنت تعتقد
   أن هناك طريقة أفضل."

4. كن منفتحاً للتغيير
   "هذه نقطة رائعة. سأقوم بتحديثها."
   "لم أكن أفكر في تلك الحالة. دعني أصلحها."

5. ادفع للخلف باحترام (عند الاقتضاء)
   "أفهم قلقك، ولكن في هذه الحالة،
   ناقشنا في اجتماع الفريق أن هذا
   النهج يتماشى مع أهداف بنيتنا."

6. ضع علامة محلولة
   - إصلاح المشكلة
   - الرد بما غيرته
   - وضع علامة على المحادثة على أنها محلولة

تجنب: أن تصبح دفاعياً، الجدال بلا داعٍ، أو تجاهل الملاحظات. هذه السلوكيات تضر بديناميكيات الفريق.

حالات مراجعة GitHub

تعليق:
- ملاحظات عامة بدون موافقة صريحة
- استخدم لـ: الأسئلة، الاقتراحات، المناقشات

موافقة:
- ✅ الكود يبدو جيداً للدمج
- استخدم عندما: راجعت بدقة ووافقت

طلب تغييرات:
- ❌ يجب إصلاح المشكلات قبل الدمج
- استخدم لـ: الأخطاء، المشكلات الأمنية، المشاكل الكسرية

نصيحة احترافية:
قدم المراجعة كدفعة بدلاً من تعليق واحد في كل مرة
- راجع PR بالكامل أولاً
- انقر على "بدء مراجعة"
- أضف جميع التعليقات
- انقر على "إنهاء المراجعة" واختر الحالة

مثال على سير عمل المراجعة

1. منظور المراجع:

# سحب الفرع محلياً
git fetch origin
git checkout feature/new-payment-gateway

# تشغيل الاختبارات
php artisan test

# مراجعة التغييرات على GitHub
- قراءة وصف PR
- التحقق من الملفات المتغيرة
- إضافة تعليقات (بدء مراجعة)
- الاختبار محلياً إذا كان معقداً
- تقديم المراجعة (موافقة/طلب تغييرات)

2. منظور المؤلف:

# معالجة الملاحظات
git checkout feature/new-payment-gateway

# إجراء التغييرات
# ... تحرير الملفات ...

git add .
git commit -m "Address review feedback: add validation"
git push origin feature/new-payment-gateway

# الرد على التعليقات
- "تم الإصلاح في الالتزام abc123"
- وضع علامة على المحادثات على أنها محلولة

# طلب إعادة المراجعة
- انقر على زر "طلب إعادة المراجعة"

أدوات مراجعة الكود الآلية

أتمتة الفحوصات الروتينية بحيث يركز البشر على المنطق والتصميم:

الأدوات الشائعة:

PHP CodeSniffer: أسلوب الكود والمعايير
PHPStan: التحليل الثابت، التحقق من النوع
Psalm: التحليل الثابت، سلامة النوع
PHP CS Fixer: تنسيق الكود التلقائي
SonarQube: جودة الكود والأمان
Codecov: تقارير تغطية الاختبار

مثال GitHub Actions:

name: Code Review Automation

on: [pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Run PHPStan
        run: ./vendor/bin/phpstan analyse

      - name: Check code style
        run: ./vendor/bin/php-cs-fixer fix --dry-run

      - name: Run tests with coverage
        run: php artisan test --coverage

أفضل ممارسة: أتمتة فحوصات الأسلوب والبناء. يجب أن يركز البشر على المنطق والبنية وقابلية الصيانة.

أفضل ممارسات حجم المراجعة

حجم PR المثالي:
- أقل من 400 سطر من الكود
- مركز على ميزة/إصلاح واحد
- قابل للمراجعة في 30 دقيقة أو أقل

إذا كان PR كبيراً جداً:
1. قسّم إلى PRs أصغر
2. راجع على مراحل (البنية أولاً، ثم التفاصيل)
3. جدولة جلسة برمجة ثنائية
4. استخدم "مسودة PR" للحصول على ملاحظات مبكرة

قالب وصف PR:

## ماذا
وصف موجز للتغييرات

## لماذا
السياق والدافع

## كيف
النهج التقني

## الاختبار
كيفية اختبار هذا التغيير

## لقطات الشاشة (إذا كانت واجهة مستخدم)
صور قبل/بعد

## قائمة التحقق
- [ ] تمت إضافة/تحديث الاختبارات
- [ ] تم تحديث التوثيق
- [ ] لا توجد تغييرات كسرية (أو موثقة)

آداب مراجعة الكود

للمراجعين:
✓ راجع بسرعة (في غضون 24 ساعة)
✓ كن شاملاً ولكن ليس صارماً للغاية
✓ ميّز بين "يجب الإصلاح" و "من الجيد أن يكون"
✓ فكر في قول "LGTM" (يبدو جيداً بالنسبة لي) عند الاقتضاء
✓ انهِ بكلمات مشجعة

للمؤلفين:
✓ احتفظ بـ PRs صغيرة ومركزة
✓ اكتب أوصافاً واضحة
✓ رد على جميع التعليقات
✓ لا تفرض الدفع بعد بدء المراجعة
✓ قل "شكراً" للمراجعات

للفرق:
✓ حدد إرشادات المراجعة
✓ حدد توقعات وقت الاستجابة
✓ استخدم التسميات (needs-review, reviewed-approved)
✓ تناوب المراجعين لمشاركة المعرفة
✓ احتفل بالمراجعات الجيدة في اجتماعات الفريق

تمرين عملي:

راجع هذا الكود:

public function store(Request $request) {
    $user = new User;
    $user->name = $request->name;
    $user->email = $request->email;
    $user->password = $request->password;
    $user->save();

    return redirect('/dashboard');
}

مهمتك: اكتب تعليقات المراجعة لتحديد المشكلات واقتراح التحسينات.

نموذج تعليقات المراجعة:

مشكلة أمنية: "⚠️ كلمة المرور مخزنة بنص عادي. يجب علينا تجزئتها: $user->password = Hash::make($request->password);"
التحقق مفقود: "يجب علينا التحقق من المدخلات قبل الحفظ. فكر في إضافة: $request->validate(['name' => 'required', 'email' => 'required|email|unique:users', 'password' => 'required|min:8']);"
معالجة الأخطاء: "ماذا يحدث إذا فشل save()؟ لنضف معالجة الأخطاء ورسالة نجاح."
نهج حديث: "فكر في استخدام التعيين الجماعي: User::create($request->validated()); (مع تعيين خاصية $fillable)"

الملخص

في هذا الدرس، تعلمت:

مراجعات الكود تحسن الجودة، وتلتقط الأخطاء، وتشارك المعرفة
راجع الوظيفة، التصميم، الجودة، الاختبار، الأمان، والأداء
قدم ملاحظات بناءة: كن لطيفاً، اشرح لماذا، قدم الحلول
رد بشكل احترافي: لا تأخذها على محمل شخصي، اطرح الأسئلة، كن منفتحاً
استخدم ميزات مراجعة GitHub: التعليقات، الاقتراحات، الموافقة/طلب التغييرات
أتمتة الفحوصات الروتينية بحيث يركز البشر على المنطق والبنية
احتفظ بـ PRs صغيرة (أقل من 400 سطر) لمراجعات فعالة

التالي: في الدرس التالي، سنعالج حل تعارضات الدمج بثقة!