مراجعات الكود حلبة مصارعة؟ كيف أنقذتنا خطاطيف ما قبل الإيداع (Pre-commit Hooks) من جحيم الجدالات

يا جماعة الخير، السلام عليكم ورحمة الله وبركاته. معكم أخوكم أبو عمر.

خلوني أحكي لكم قصة صارت معي قبل كم سنة، أيام ما كنت شغال على مشروع ضخم ومهم لعميل “مستعجل” كالعادة. الفريق كان شغال ليل نهار، القهوة ما كانت تفارق مكاتبنا، والكل كان على أعصابه عشان نسلم المشروع في وقته. في يوم من الأيام، واحد من الشباب الطيبة في الفريق، خلينا نسميه “سامر”، رفع طلب مراجعة كود (Pull Request) لجزئية كان شغال عليها. من ناحية منطقية، الكود كان عبقري، حل مشكلة معقدة بطريقة ذكية جداً.

لكن… آه يا “لكن” هاي. لما فتحنا الكود عشان نراجعه، تحولت جلسة المراجعة لحلبة مصارعة كلامية. واحد علّق: “ليش مستخدم 4 مسافات للمسافة البادئة واحنا متفقين على 2؟”. والثاني كتب: “يا سامر، نسيت الفاصلة المنقوطة في السطر 54!”. والثالث، بكل جدية، كتب تعليق من ثلاث فقرات يشرح فيه ليش لازم نستخدم علامات التنصيص المفردة (‘) بدل المزدوجة (“).

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

هذا الموقف، وغيره كثير، كان الشرارة اللي خلتني أبحث عن حل جذري ينهي هاي المهزلة. حل يخلينا نركز على ما هو مهم: منطق الكود، بنيته، وأمانه. وهنا كانت بداية علاقة الحب بيني وبين ما يسمى بـ “خطاطيف ما قبل الإيداع” أو الـ Pre-commit Hooks.

ما هي خطاطيف ما قبل الإيداع (Pre-commit Hooks)؟

ببساطة شديدة، تخيل إن عندك حارس أمن (Bouncer) واقف على باب مستودع الكود بتاعك (Git Repository). أي كود بحاول يدخل (يصير له commit)، الحارس بوقفه وبيفحصه حسب قائمة قوانين محددة. لو الكود مطابق للقوانين، بيسمح له بالدخول. لو فيه أي مخالفة، بيرجعه لصاحبه وبيقول له: “ارجع صلح مشاكلك وتعال!”.

هذا الحارس هو الـ Pre-commit Hook. هي عبارة عن سكربتات (نصوص برمجية) صغيرة تشتغل تلقائياً قبل ما عملية الـ git commit تكتمل. إذا نجحت هذه السكربتات، تتم عملية الـ commit. إذا فشلت، تتوقف العملية كلها، وبتجبرك تصلح المشكلة قبل ما الكود “الملخبط” يوصل للمستودع الرئيسي.

لماذا كانت حياتنا جحيماً قبلها؟ (المشكلة بالتفصيل)

قبل ما نتبنى هذا النهج، كانت مشاكلنا تتلخص في ثلاث نقاط رئيسية:

1. الجدالات البيزنطية في مراجعات الكود

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

2. الكود غير المتناسق (Inconsistent Codebase)

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

3. اكتشاف الأخطاء البسيطة متأخراً

كم مرة رفعت كود للـ CI/CD pipeline (خط أنابيب التكامل والنشر المستمر) عشان تكتشف بعد 5 دقائق إن العملية فشلت بسبب خطأ سخيف مثل متغير غير مستخدم أو import ناقص؟ هذه الدقائق تتراكم وتتحول لساعات مهدرة. الـ Pre-commit hooks تلتقط هذه الأخطاء البسيطة على جهازك المحلي في ثوانٍ، قبل أن يصل الكود لأي مكان آخر.

الحل السحري: إطار عمل `pre-commit`

صحيح أن Git يوفر نظام Hooks مدمج في مجلد .git/hooks، لكن إدارته ومشاركته مع الفريق أمر معقد. والحل العملي اللي بيستخدمه أغلب الناس اليوم هو إطار عمل مكتوب بلغة بايثون اسمه pre-commit. هذه الأداة تسهل إدارة وتوزيع هذه الخطاطيف بشكل لا يصدق.

التركيب والإعداد الأولي

الأمر بسيط جداً. أولاً، تحتاج لتركيب الأداة (عادة عبر pip الخاص ببايثون):

pip install pre-commit

ثانياً، في جذر مشروعك، تقوم بإنشاء ملف إعدادات اسمه .pre-commit-config.yaml. هذا الملف هو قلب النظام، وفيه تحدد “القوانين” التي سيطبقها حارس الأمن تبعنا.

ثالثاً، تقوم بتفعيل الخطاطيف في مستودع Git المحلي الخاص بك بالأمر التالي:

pre-commit install

هذا الأمر لا تحتاجه إلا مرة واحدة لكل مشروع. والآن، مع كل git commit ستقوم به، ستعمل هذه الخطاطيف تلقائياً.

مثال عملي: لننظف الكود تلقائياً!

لنفترض أننا نعمل على مشروع بايثون مع بعض ملفات الواجهة الأمامية (JavaScript, CSS). ملف .pre-commit-config.yaml النموذجي قد يبدو كالتالي:

# .pre-commit-config.yaml

# هذا الملف يحدد قائمة الخطاطيف التي ستعمل قبل كل commit
repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0 # استخدم دائماً نسخة محددة
    hooks:
    # خطاطيف أساسية ومفيدة جداً
    -   id: trailing-whitespace   # يحذف المسافات الزائدة في نهاية الأسطر
    -   id: end-of-file-fixer     # يتأكد من وجود سطر فارغ في نهاية كل ملف
    -   id: check-yaml            # يفحص صحة ملفات YAML (مثل هذا الملف نفسه!)
    -   id: check-added-large-files # ينبهك لو حاولت إضافة ملفات كبيرة الحجم (أكبر من 5 ميجا مثلاً)

-   repo: https://github.com/psf/black
    rev: 24.4.2
    hooks:
    -   id: black # المنسق السحري لكود البايثون. لا جدال بعد اليوم!

-   repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.4
    hooks:
    -   id: ruff # مدقق (linter) سريع جداً لكود البايثون، يكتشف الأخطاء والمشاكل
      args: [--fix] # نطلب منه محاولة إصلاح الأخطاء تلقائياً

-   repo: https://github.com/prettier/prettier
    rev: 3.2.5
    hooks:
    -   id: prettier # المنسق المقابل لـ Black لعالم الويب (JS, TS, CSS, JSON, etc.)

كيف يعمل السحر؟

بعد إعداد الملف وتشغيل pre-commit install، السيناريو سيكون كالتالي:

1. تكتب كودك كالمعتاد، ربما بمسافات عشوائية وبدون الاهتمام بالتنسيق.
2. تنفذ الأمرين: git add . ثم git commit -m "إضافة ميزة جديدة".
3. هنا، يبدأ الـ pre-commit بالعمل. سيظهر لك في الطرفية (Terminal) أنه يقوم بتشغيل الخطاطيف واحداً تلو الآخر على الملفات التي غيرتها.
4. إذا كان هناك خطأ لا يمكن إصلاحه تلقائياً (مثلاً خطأ في بناء الجملة)، ستفشل العملية مع رسالة واضحة تخبرك بالملف والسطر المشكل.
5. إذا كانت هناك مشاكل تنسيق، ستقوم أدوات مثل black و prettier بإصلاح الملفات مباشرة. ستفشل عملية الـ commit، ولكنها ستخبرك بأنها قامت بتعديل الملفات. كل ما عليك فعله هو مراجعة التعديلات ثم تنفيذ git add . و git commit ... مرة أخرى.
6. إذا كان كل شيء سليماً، ستتم عملية الـ commit بنجاح.

الجميل في الأمر أن الكود الذي يصل إلى طلب المراجعة (Pull Request) يكون نظيفاً ومنسقاً وخالياً من الأخطاء السطحية بشكل تلقائي. مراجعة الكود الآن تركز على ما هو مهم حقاً.

نصائح من خبرة أبو عمر 🧔

• ابدأ بالبساطة: لا تضف 20 خطافاً من أول يوم وتخنق فريقك. ابدأ بالأساسيات مثل إزالة المسافات الزائدة ومنسق كود واحد (مثل Black أو Prettier). ثم أضف المزيد تدريجياً حسب حاجة الفريق.
• الاتفاق أهم من الأداة: قبل فرض أداة تنسيق معينة (formatter)، تحدث مع فريقك. الهدف هو الاتفاق على معيار واحد والتخلص من الجدل. الأداة هي مجرد وسيلة لتطبيق هذا الاتفاق آلياً.
• اجعلها جزءاً من الـ CI: لا تكتفِ بتشغيل الخطاطيف على أجهزة المطورين فقط. أضف خطوة في الـ CI/CD pipeline تقوم بتشغيل pre-commit run --all-files. هذه الخطوة تمثل “شبكة الأمان” التي تضمن عدم مرور أي كود غير متوافق، حتى لو نسي أحد المطورين تفعيل الخطاطيف على جهازه.
• لا تخترع العجلة: قبل كتابة خطاف مخصص لمشروعك، ابحث جيداً. هناك آلاف الخطاطيف الجاهزة التي تغطي معظم الحالات الشائعة.

الخلاصة: ركز على ما يهم حقاً

في النهاية، الهدف من هندسة البرمجيات هو بناء منتجات ذات قيمة، وليس كتابة كود بأسلوب تنسيق مثالي. الـ Pre-commit hooks هي أداة بسيطة لكنها قوية جداً، تسمح لنا بأتمتة الجانب الممل والمكرر من عملنا (الجدالات الأسلوبية)، وتحرر وقتنا وطاقتنا الذهنية للتركيز على التحديات الحقيقية: التصميم المعماري الجيد، الخوارزميات الفعالة، وتجربة المستخدم الممتازة.

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