هندسة البرمجيات والـ Backend الأدلة التقنية

هندسة البرمجيات Software Engineering: من كود يعمل إلى نظام

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

هندسة البرمجيات Software Engineering: من كود يعمل إلى نظام

تكتب في يوم واحد سكربتاً صغيراً بلغة Python يقرأ ملف الطلبات الذي يصدره المتجر الإلكتروني، ويجمع المبيعات لكل شهر، ويطبع ثلاثة أسطر، فيفرح المدير لأن التقرير الذي كان يأخذ من المحاسب ساعتين صار يخرج في ثانية. وبعد شهر يطلب منك إضافة ضريبة القيمة المضافة VAT، ثم يطلب خصم المرتجعات، ثم يبدأ المتجر بقبول الدولار، ثم يريد قسم الفروع تقريراً للمتجر الإلكتروني وحده، ثم يريد المحاسب ملف CSV بدلاً من الشاشة. وكل طلب يأخذ منك عشر دقائق وبضعة أسطر، والسكربت ما زال «يعمل». وبعد سنة يأتي زميل آخر ليضيف عملة جديدة وأنت في إجازة، ويكتشف المحاسب أن أرقام فبراير تختلف عن كشف البنك بخمسة وخمسين ريالاً، ولا أحد يعرف منذ متى ولا لماذا، ولا يجرؤ أحد على تعديل السكربت لأن أحداً لا يعرف ما الذي سوف يتعطل بعد التعديل.

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

وسوف نناقش في هذا المقال ما يلي:

  • ما الذي يميز هندسة البرمجيات عن البرمجة، ولماذا يقول فريق Google إنها «البرمجة مضروبة في الزمن».
  • من أين جاء المصطلح، وما الذي تعلمناه من Brooks وParnas وLehman، وما هو دليل SWEBOK.
  • الأنشطة التي يقوم بها المهندس حول الكود: المتطلبات Requirements والتصميم Design والاختبار Testing والمراجعة Code Review والتكامل المستمر CI والتشغيل Operations.
  • لماذا تكلف الصيانة Maintenance أكثر من الكتابة، وقوانين Lehman لتطور البرمجيات، وحادثة Ariane 5.
  • كيف تقيس صحة الكود ومسار التسليم بأرقام بسيطة، ومنها مقاييس DORA.
  • تجربة عملية على سكربت التقرير نفسه في ثلاث نسخ داخل مستودع Git: السكربت، ثم السكربت الذي كبر، ثم وحدة Module مختبرة لها خط CI نشغله محلياً بأداة act، مع أرقام حقيقية للأسطر والتعقيد والاختبارات.

ما الفرق بين البرمجة Programming وهندسة البرمجيات؟

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

وأوضح صياغة عملية لهذا الفرق جاءت من فريق Google في الفصل الأول من كتاب Software Engineering at Google، حيث كتب Titus Winters أنهم يقولون داخل الشركة إن هندسة البرمجيات هي البرمجة مضروبة في الزمن Programming Integrated over Time، وذكر ثلاثة فروق أساسية بين البرمجة وهندسة البرمجيات: الزمن Time، والحجم Scale، والمقايضات Trade-offs.

الزمن Time: كم سنة سوف يعيش هذا الكود؟

عندما يتعلم المطور البرمجة يكون عمر الكود الذي يكتبه ساعات أو أياماً، فالواجب يسلم مرة واحدة ولا يعود إليه أحد. أما الكود الذي تعتمد عليه شركة فقد يعيش عشر سنوات، وخلال هذه السنوات سوف تتغير نسخة اللغة، والمكتبات التي يعتمد عليها، ونظام التشغيل، والقوانين، وطريقة عمل الشركة نفسها. لذلك السؤال الأول الذي يسأله المهندس قبل أي قرار هو: كم سوف يعيش هذا الكود؟ فإذا كان سكربتاً لمرة واحدة لنقل بيانات قديمة فلا داعي لاختبارات وخط CI، وإذا كان سوف يحسب أرقاماً مالية كل شهر لسنوات فكل ساعة تضعها فيه اليوم توفر أياماً لاحقاً.

ويذكر الفصل نفسه ما يسمونه قانون Hyrum، Hyrum's Law، ومعناه أنه إذا كان لديك عدد كاف من المستخدمين فإن كل سلوك يمكن ملاحظته في نظامك سوف يعتمد عليه أحدهم، حتى لو لم تعد به في أي توثيق. وسوف ترى مثالاً صغيراً على ذلك في التجربة، فالنسخة القديمة من السكربت تطبع 630.6 والنسخة الجديدة تطبع 630.60، وهذا تغيير لا يراه المطور شيئاً، ولكن إذا كان المحاسب قد بنى معادلة في جدول البيانات تقرأ هذا السطر فقد تتعطل معادلته.

الحجم Scale: كم شخصاً سوف يعدل الكود؟

الكود الذي يكتبه شخص واحد ويقرأه هو وحده يستطيع أن يعتمد على ذاكرة كاتبه، أما عندما يصبح عدد من يعدلون الكود ثلاثة أو ثلاثين فإن كل ما في رأس الكاتب يجب أن يخرج إلى مكان يراه الجميع: المتطلبات في وثيقة أو تذكرة، وقرارات التصميم في سجل قرارات، والسلوك المتوقع في اختبارات، وطريقة التشغيل في ملف README وخط CI. وقد كتب Fred Brooks في كتاب The Mythical Man-Month سنة 1975 جملته المشهورة التي صارت تسمى قانون Brooks: إضافة مبرمجين إلى مشروع برمجيات متأخر تجعله أكثر تأخراً، والسبب أن كل شخص جديد يحتاج وقتاً ليتعلم، وأن عدد قنوات التواصل بين أفراد الفريق يزيد أسرع من عددهم.

وفي الفصل الأول من الكتاب نفسه، وعنوانه The Tar Pit، رسم Brooks مربعاً يشرح لماذا يبدو البرنامج الذي يكتبه شخص في المرآب أرخص بكثير من البرنامج الذي تبيعه شركة. فالبرنامج Program الذي يعمل عند كاتبه يحتاج ثلاثة أضعاف الجهد ليصبح منتجاً برمجياً Programming Product يستخدمه غيره، لأنه يحتاج اختباراً وتوثيقاً وتعاملاً مع المدخلات الخاطئة، ويحتاج ثلاثة أضعاف الجهد ليصبح جزءاً من نظام Programming System يتكامل مع برامج أخرى عبر واجهات واضحة، والجمع بين الاثنين، أي منتج يستخدمه غيرك داخل نظام أكبر، يكلف تسعة أضعاف البرنامج الأول تقريباً. والصورة التالية تبين المربع:

مربع Fred Brooks: في الزاوية برنامج يعمل عند كاتبه، وإلى جانبه منتج برمجي بثلاثة أضعاف الجهد لأنه مختبر وموثق، وتحته جزء من نظام بثلاثة أضعاف لأنه يتكامل عبر واجهات، وفي الزاوية المقابلة منتج داخل نظام بتسعة أضعاف الجهد
البرنامج الذي يعمل عندك هو أصغر خانة في المربع، وما يستخدمه غيرك داخل نظام أكبر يكلف قرابة تسعة أضعافه

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

المقايضات Trade-offs: لا يوجد قرار مجاني

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

من أين جاء المصطلح؟ أزمة البرمجيات Software Crisis

في أكتوبر 1968 عقدت اللجنة العلمية في حلف NATO مؤتمراً في مدينة Garmisch الألمانية عنوانه Software Engineering، واختار المنظمون هذا الاسم عمداً ليقولوا إن بناء البرمجيات يجب أن يستند إلى الأسس النظرية والممارسات المنضبطة التي تستند إليها الهندسة التقليدية. والسبب أن المشاريع الكبيرة في ذلك الوقت، مثل أنظمة التشغيل للحاسبات الكبيرة، كانت تتأخر سنوات وتتجاوز ميزانيتها وتصل بأخطاء كثيرة، وسمى المشاركون هذا الوضع أزمة البرمجيات Software Crisis.

وبعد ذلك ظهرت الأعمال التي ما زلنا نعتمد عليها، ونذكر منها أربعة سوف تقابلها في هذا المقال وفي المقالات التي بعده:

  • David Parnas سنة 1972: نشر في مجلة Communications of the ACM ورقة On the Criteria to Be Used in Decomposing Systems into Modules، وقال فيها إن أفضل طريقة لتقسيم النظام إلى وحدات ليست خطوات المعالجة، وإنما القرارات التي يحتمل أن تتغير، فكل وحدة تخفي قراراً واحداً عن بقية النظام، وهذا ما يسمى إخفاء المعلومات Information Hiding. وسوف نشرحها بالتفصيل في مقال الاقتران والتماسك.
  • Fred Brooks سنة 1975 ثم 1986: بعد كتاب The Mythical Man-Month كتب مقالاً بعنوان No Silver Bullet قال فيه إنه لا توجد أداة أو طريقة واحدة سوف تحسن إنتاجية البرمجيات عشرة أضعاف خلال عقد، والسبب أنه فرق بين التعقيد الأساسي Essential Complexity الذي يأتي من المشكلة نفسها، مثل قواعد الضريبة والعملات والمرتجعات، والتعقيد العرضي Accidental Complexity الذي يأتي من أدواتنا، مثل إدارة الذاكرة يدوياً، والأدوات تقلل الثاني فقط.
  • Meir Lehman سنة 1980: نشر في مجلة Proceedings of the IEEE ورقة Programs, Life Cycles, and Laws of Software Evolution التي صاغ فيها قوانين تطور البرمجيات، ونعود إليها في قسم الصيانة.
  • دليل SWEBOK: كتاب مرجعي تصدره جمعية الحاسب في IEEE يجمع المعرفة المتفق عليها في المهنة، وصدرت نسخته الثالثة سنة 2014 والرابعة سنة 2024، ونسخته الحالية V4.0a فيها 18 مجالاً معرفياً Knowledge Area، ومنها مجالات أضيفت في النسخة الرابعة مثل معمارية البرمجيات Software Architecture وعمليات هندسة البرمجيات Software Engineering Operations وأمن البرمجيات Software Security.

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

ماذا يفعل مهندس البرمجيات غير كتابة الكود؟ أنشطة دورة الحياة Software Lifecycle

كتابة الكود، أو ما يسميه SWEBOK البناء Construction، هي نشاط واحد من أنشطة كثيرة، وكل نشاط منها يجيب عن سؤال لو تركته دون إجابة لظهر في مكان آخر بكلفة أعلى. والصورة التالية تبين الأنشطة حول الكود في دورة واحدة:

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

المتطلبات Requirements: ماذا نبني بالضبط؟

عندما طلب المدير «خصم المرتجعات» لم يسأل أحد: هل المرتجع بالدولار يحول إلى الريال قبل خصمه؟ وهل يخصم مع الضريبة أم بدونها إذا كان التقرير بالضريبة؟ وهذه الأسئلة هي عمل المتطلبات، فالمتطلب الجيد يكتب الحالات الحدية ويعطي أمثلة بأرقام، مثل «مرتجع بقيمة 20 دولاراً يخصم 75 ريالاً». وفي التجربة سوف ترى أن خطأ فبراير كله سببه سؤال لم يسأل. وقد شرحنا هذا النشاط بالتفصيل في دليل هندسة المتطلبات Requirements Engineering.

التصميم Design: كيف نقسم الكود؟

التصميم يجيب عن سؤال: أين يوضع كل قرار؟ فسعر صرف الدولار قرار، وطريقة التقريب قرار، وصيغة ملف الطلبات قرار، وكل قرار منها يجب أن يكون في مكان واحد حتى إذا تغير لا تبحث عنه في عشرة أماكن. وهذه بالضبط فكرة Parnas عن إخفاء المعلومات. وفي النسخة الثالثة من التجربة سوف يكون لكل قرار ملف: money.py للعملات والضريبة والتقريب، وorders.py لقراءة الملف، وreport.py للحساب. وللتمييز بين التصميم والمعمارية وتصميم الأنظمة راجع مقال التصميم والمعمارية، وللمبادئ التي توجه هذه القرارات راجع مبادئ التصميم Design Principles.

البناء Construction: كود يقرؤه غيرك

البناء هو كتابة الكود نفسه، ولكن بمعايير تجعل غيرك يستطيع قراءته وتعديله: أسماء واضحة، ودوال قصيرة لها مهمة واحدة، وأنواع Types مكتوبة، ومدقق Linter يوحد الأسلوب، ونسخ Versions ثابتة للمكتبات. ومن قرارات البناء المهمة في التقرير اختيار النوع الصحيح للمال، فالنسخة الأولى تستخدم float وتطبع 540.7900000000001، والسبب أن الأرقام العشرية الثنائية لا تمثل 0.1 بدقة كما شرحنا في مقال الأرقام العشرية Floating Point، والحل في Python هو النوع Decimal.

الاختبار Testing: كيف نعرف أن السلوك لم يتغير؟

الاختبار في هندسة البرمجيات ليس فقط للتأكد من أن الكود الجديد يعمل، وإنما للتأكد من أن السلوك القديم لم يتغير عندما أضفت الجديد، وهذا ما يسمى اختبار التراجع Regression Testing. فكل اختبار تكتبه اليوم هو متطلب مكتوب بلغة ينفذها الحاسب، وعندما يضيف زميلك عملة جديدة بعد سنة فإن الاختبارات هي التي تخبره بما تعطل قبل أن يخبره المحاسب. وقد شرحنا أنواع الاختبارات في أنواع الاختبارات للمبتدئين وطريقة كتابة اختبار الوحدة الجيد في اختبارات الوحدة Unit Tests عملياً.

المراجعة Code Review: عين ثانية قبل الدمج

المراجعة تجيب عن سؤال لا يجيب عنه الاختبار: هل هذا الكود مفهوم، وهل هذا هو المكان الصحيح للتعديل، وهل هناك حالة لم يفكر فيها الكاتب؟ فالمراجع الذي يقرأ تعديل المرتجعات في النسخة الثانية سوف يسأل غالباً: لماذا يخرج فرع المرتجع بالأمر continue قبل تحويل العملة؟ وهذا السؤال وحده كان سيمنع خطأ فبراير. وقد شرحنا طريقة المراجعة المفيدة في مراجعة الكود Code Review.

التكامل المستمر CI: الآلة تتذكر ما ينساه البشر

خط التكامل المستمر Continuous Integration يشغل المدقق والاختبارات على كل تعديل قبل دمجه، فلا يعتمد الفريق على أن كل مطور تذكر أن يشغل الاختبارات على جهازه. وفي التجربة سوف يفشل الخط مرتين: مرة بسبب سطر طويل وترتيب Imports، ومرة بسبب خطأ نوع حقيقي في إضافة اليورو، وفي المرتين لم يصل الخطأ إلى الفرع الرئيسي. وللمفهوم كاملاً من الدفع إلى النشر راجع مفهوم CI/CD للمبتدئين.

التشغيل Operations والصيانة Maintenance

بعد التسليم يبدأ الجزء الأطول من عمر الكود: يعمل على سيرفر، ويراقب، وتصل عنه بلاغات، ويعدل. ويخصص SWEBOK الرابع مجالاً كاملاً لعمليات هندسة البرمجيات، ومجالاً آخر للصيانة، وهذا هو موضوع القسم التالي لأنه المكان الذي تذهب إليه أغلب الكلفة.

لماذا تكلف الصيانة Maintenance أكثر من الكتابة؟

الصورة الشائعة عن الصيانة أنها إصلاح أخطاء، ولكن فصل الصيانة في SWEBOK الرابع يقول إن الدراسات والاستبيانات عبر السنين بينت أن أكثر من 80% من جهد الصيانة يذهب إلى تحسين البرمجيات وتكييفها، وليس إلى إصلاح الأخطاء، وإن جمع التحسينات والإصلاحات في تقرير واحد يجعل الإدارة تظن أن الإصلاحات تكلف أكثر مما تكلف فعلاً. ويقسم الدليل، نقلاً عن المعيار ISO/IEC/IEEE 14764، طلبات التعديل إلى خمسة أنواع، ويضيف المعيار نوعاً سادساً:

  • الصيانة التصحيحية Corrective: إصلاح خطأ اكتشف بعد التسليم، مثل خطأ المرتجع بالدولار في التجربة.
  • الصيانة الوقائية Preventive: إصلاح خطأ كامن قبل أن يظهر في النظام الحي، مثل رفض العملة غير المعروفة بدلاً من تجاهلها بصمت.
  • الصيانة التكيفية Adaptive: تعديل الكود ليبقى صالحاً في بيئة تغيرت، مثل ترقية نسخة Python أو تغير صيغة ملف التصدير من المتجر.
  • الصيانة الإضافية Additive: إضافة وظيفة جديدة، مثل دعم اليورو أو تصفية الفروع.
  • الصيانة التحسينية Perfective: تحسين التصميم أو الأداء دون تغيير الوظيفة، مثل تحويل السكربت إلى وحدة في النسخة الثالثة.
  • الصيانة الطارئة Emergency: تعديل غير مخطط يجرى بسرعة لإبقاء النظام يعمل، وهو النوع الذي يتمنى كل فريق أن يقل.
طلب تعديل يتفرع إلى مجموعتين: التصحيح وفيها الصيانة التصحيحية والوقائية، والتحسين وفيها التكيفية والإضافية والتحسينية، ومكتوب فوق مجموعة التحسين أكثر من 80% من جهد الصيانة بحسب SWEBOK، ولكل نوع مثال من سكربت التقرير
أغلب ما يسمى صيانة هو إضافة وتكييف، أي تطوير مستمر للكود نفسه

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

قوانين Lehman لتطور البرمجيات Laws of Software Evolution

درس Meir Lehman مع زملائه تطور أنظمة حقيقية في IBM وغيرها على مدى عشرين سنة تقريباً، وخرج بثمانية قوانين يسردها SWEBOK الرابع في فصل الصيانة. وأهم قانونين للمبتدئ هما الأولان:

  • التغير المستمر Continuing Change: البرنامج المستخدم في العالم الحقيقي يجب أن يتكيف باستمرار، وإلا أصبح أقل نفعاً مع الوقت. وهذا ما حدث للسكربت: لم يكن أمامه خيار إلا أن يتغير.
  • التعقيد المتزايد Increasing Complexity: كلما تطور البرنامج زاد تعقيده، إلا إذا بذل جهد مخصص لإبقائه كما هو أو لتقليله. ولاحظ أن القانون لا يقول إن التعقيد يزيد دائماً، وإنما يقول إنه يزيد إذا لم يعمل أحد على تقليله.

والقوانين الستة الباقية هي التنظيم الذاتي Self-Regulation، وثبات معدل العمل Invariant Work Rate، والمحافظة على الألفة Conservation of Familiarity، والنمو المستمر Continuing Growth، وتراجع الجودة Declining Quality، ونظام التغذية الراجعة Feedback System. ومن أهمها للفرق قانون الألفة، فهو يقول إن كل من يعمل مع النظام، من المطورين إلى المستخدمين، يجب أن يبقى ملماً بسلوكه، وإن النمو الكبير في إصدار واحد يضيع هذا الإلمام، لذلك تبقى الإضافات في كل إصدار متقاربة الحجم تقريباً. وسوف ترى قانون التعقيد المتزايد بالأرقام في التجربة، فالتعقيد الدوري لدالة التقرير ارتفع من 3 إلى 16 عندما أضفنا خمسة طلبات صغيرة، ثم نزل أكبر تعقيد لدالة إلى 5 عندما بذلنا جهداً مخصصاً لتقسيم الكود:

رسم لأكبر تعقيد دوري لدالة في النسخ الثلاث من سكربت التقرير: 3 في النسخة الأولى، ثم 16 في النسخة الثانية بعد خمسة طلبات، ثم 5 في النسخة الثالثة بعد التقسيم، ومؤشر قابلية الصيانة ينزل من 75 إلى 52 ثم يعود فوق 59
قانون التعقيد المتزايد بأرقام التجربة: التعقيد يرتفع مع كل طلب صغير، ولا ينزل إلا بجهد مقصود

شيخوخة البرمجيات Software Aging

في سنة 1994 قدم Parnas في مؤتمر ICSE ورقة بعنوان Software Aging قال فيها إن البرمجيات تشيخ مثل البشر لسببين: الأول أن العالم حولها يتغير ولا يعدلها أحد، فتصبح أقل نفعاً، والثاني أن من يعدلونها لا يفهمون تصميمها الأصلي فيضيفون التعديلات بطريقة تخالفه، فيصبح كل تعديل لاحق أصعب. ونصح بأن تكتب الوثائق التي تشرح سبب كل قرار، وأن يراجع كل تعديل من شخص يفهم التصميم، وأن يعاد هيكلة الكود Refactoring عندما يتراكم عليه التعديل. وكل ممارسة في هذه النصيحة صار لها اليوم اسم وأداة: سجلات القرارات المعمارية ADR التي شرحناها في توثيق المعمارية، وطلبات الدمج مع المراجعة، والدين التقني Technical Debt الذي شرحنا قياسه في مقال الدين التقني.

💡
في 4 يونيو 1996 انفجر الصاروخ Ariane 5 في رحلته الأولى بعد قرابة 40 ثانية من الإطلاق. وبحسب تقرير لجنة التحقيق الذي نشرته وكالة الفضاء الأوروبية ESA، فإن نظام القياس بالقصور الذاتي استخدم برمجيات منقولة من Ariane 4، وفيها تحويل من رقم عشري 64 بت إلى عدد صحيح 16 بت لقيمة السرعة الأفقية، وهذا التحويل كان آمناً على مسار Ariane 4، ولكن Ariane 5 أسرع أفقياً، فتجاوزت القيمة الحد وتوقف النظام ونسخته الاحتياطية معاً، لأنهما يشغلان البرمجيات نفسها. والأغرب أن هذه الدالة لم يكن لها أي عمل بعد الإطلاق في Ariane 5. والدرس لكل مطور أن الكود الذي يعاد استخدامه يحمل معه افتراضات كتبت لبيئة أخرى، وأن المتطلبات الجديدة لم تراجع على الكود القديم.

كيف تعرف أن الكود يشيخ؟ مقاييس Metrics بسيطة

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

  • عدد الأسطر Lines of Code: لا يقيس الجودة، ولكن نموه السريع في ملف واحد إشارة إلى أن هذا الملف يجمع أكثر من مسؤولية.
  • التعقيد الدوري Cyclomatic Complexity: عرفه Thomas McCabe سنة 1976 في ورقة A Complexity Measure، وهو عدد المسارات المستقلة في الدالة، أي عدد الشروط والحلقات زائد واحد تقريباً، ويعطي فكرة عن عدد الاختبارات التي تحتاجها الدالة لتغطي كل مساراتها. وأداة Radon تصنفه بحروف من A إلى F، فالدالة من 1 إلى 5 في الفئة A، ومن 11 إلى 20 في الفئة C. وقد شرحنا المقياس وأخاه التعقيد الإدراكي Cognitive Complexity في مقال جودة الكود.
  • مؤشر قابلية الصيانة Maintainability Index: رقم من 0 إلى 100 يجمع الأسطر والتعقيد وحجم المفردات، وهو تقريبي، وفائدته في مقارنة نسخ الملف نفسه عبر الزمن.
  • عدد الاختبارات والتغطية Coverage: التغطية تخبرك بالكود الذي لم ينفذه أي اختبار، ولكنها لا تخبرك أن الاختبارات تتحقق من الشيء الصحيح.
  • تاريخ Git: الأمر git log يخبرك بالملفات التي تتغير كثيراً، والملف الذي يتغير كثيراً وتعقيده عال هو أول مرشح لإعادة الهيكلة.

مقاييس التسليم DORA Metrics

المقاييس السابقة تقيس الكود، أما برنامج البحث DORA، الذي يصدر منذ 2014 تقرير State of DevOps وصار اليوم ضمن Google Cloud، فيقيس قدرة الفريق على تسليم التعديلات بأمان وسرعة. وبحسب دليل مقاييس DORA فإن المقاييس تنقسم إلى مجموعتين:

المجموعةالمقياسماذا يقيس
سرعة التسليم Throughputزمن التغيير Change Lead Timeالوقت من دخول التعديل إلى Git حتى وصوله إلى الإنتاج
سرعة التسليم Throughputتكرار النشر Deployment Frequencyعدد مرات النشر في فترة معينة
سرعة التسليم Throughputزمن التعافي من النشر الفاشل Failed Deployment Recovery Timeالوقت اللازم للعودة بعد نشر احتاج تدخلاً فورياً
عدم الاستقرار Instabilityنسبة فشل التغييرات Change Fail Rateنسبة عمليات النشر التي احتاجت تراجعاً أو إصلاحاً عاجلاً
عدم الاستقرار Instabilityنسبة إعادة العمل Deployment Rework Rateنسبة عمليات النشر غير المخطط لها التي جاءت بسبب حادثة في الإنتاج

وقد وجد تقرير DORA لسنة 2024 أن تبني أدوات الذكاء الاصطناعي يرفع إنتاجية الفرد ورضاه عن عمله، ولكنه ارتبط بانخفاض في سرعة التسليم واستقراره، وذكر التقرير أن الأساسيات مثل الدفعات الصغيرة Small Batches والاختبارات المتينة ما زالت حاسمة. ثم جاء تقرير 2025 بعنوان State of AI-assisted Software Development، وخلاصته أن الذكاء الاصطناعي مضخم Amplifier يكبر نقاط القوة ونقاط الضعف الموجودة أصلاً في الفريق. وهذا يعني للمطور الذي يكتب كوده بمساعدة الأدوات الجديدة أن الممارسات في هذا المقال صارت أهم وليس أقل أهمية، لأن الكود يكتب أسرع مما يراجع. وللصورة الكاملة عن ثقافة التسليم راجع ما هو DevOps؟.

تجربة عملية Lab: سكربت التقرير في ثلاث نسخ

في هذه التجربة نبني مستودع Git فيه سكربت التقرير من القصة في ثلاث نسخ: النسخة الأولى كما كتبت في اليوم الأول، والنسخة الثانية بعد خمسة طلبات، والنسخة الثالثة بعد تحويلها إلى وحدة مختبرة لها خط CI. ثم نقيس كل نسخة بالأدوات نفسها، ونشغل خط CI محلياً بأداة act، ونضيف طلباً جديداً لنرى كيف تتصرف النسخة الثالثة. وكل الأوامر تعمل داخل Containers، وملفات التجربة كاملة في مجلد lab مع المقال.

التجهيز Setup

نبني Image فيها Python 3.13.18 وGit والأدوات بنسخ ثابتة: pytest للاختبارات، وpytest-cov للتغطية، وRuff للتدقيق، وRadon وlizard لقياس التعقيد:

FROM python:3.13.18-slim
RUN apt-get update && apt-get install -y --no-install-recommends git && rm -rf /var/lib/apt/lists/*
RUN pip install --no-cache-dir pytest==9.2.0 pytest-cov==7.1.0 ruff==0.17.5 radon==6.0.1 lizard==1.26.1
WORKDIR /work

وملف الطلبات الذي نستخدمه في كل النسخ فيه 17 طلباً في ثلاثة أشهر، منها طلبات بالدولار، وطلبان ملغيان Cancelled، ومرتجعان Refund، أحدهما بالدولار:

order_id,date,branch,currency,amount,status
1001,2026-01-03,online,SAR,120.10,paid
1002,2026-01-07,online,SAR,45.20,paid
1003,2026-01-12,store,SAR,300.00,paid
1004,2026-01-19,online,USD,40.00,paid
1005,2026-01-25,store,SAR,89.90,cancelled
1006,2026-01-28,online,SAR,15.30,paid
1007,2026-02-02,store,SAR,210.70,paid
1008,2026-02-09,online,SAR,99.99,paid
1009,2026-02-14,online,USD,20.00,refund
1010,2026-02-14,online,USD,60.00,paid
1011,2026-02-20,store,SAR,150.00,refund
1012,2026-02-26,online,SAR,0.10,paid
1013,2026-03-04,store,SAR,500.00,paid
1014,2026-03-11,online,SAR,75.25,paid
1015,2026-03-18,online,USD,100.00,paid
1016,2026-03-22,store,SAR,0.20,paid
1017,2026-03-29,online,SAR,33.33,cancelled

والسكربت build-repo.sh ينشئ المستودع ويضع كل نسخة في Commit مع Tag باسمها، وهو كامل في مجلد التجربة. ونشغله داخل Container يحفظ المستودع في Volume باسم sw1-se-work حتى نعود إليه في الخطوات التالية:

docker build -t sw1-se:lab .
docker volume create sw1-se-work
docker run --rm -v sw1-se-work:/work -v "$PWD:/lab" sw1-se:lab sh /lab/build-repo.sh

النسخة الأولى Version 1: سكربت من تسعة أسطر

import csv

totals = {}
for row in csv.DictReader(open("orders.csv")):
    month = row["date"][:7]
    totals[month] = totals.get(month, 0) + float(row["amount"])

for month in sorted(totals):
    print(month, totals[month])

والمخرج سوف يكون كما يلي:

2026-01 610.5
2026-02 540.7900000000001
2026-03 708.7800000000001

في المخرج أعلاه لاحظ التالي:

  • السكربت «يعمل»، ولكن أرقامه خاطئة في ثلاثة أشياء لم يطلبها أحد بعد: الطلبات الملغية محسوبة، والمرتجعات مضافة بدل أن تخصم، والدولار يجمع كأنه ريال.
  • الرقم 540.7900000000001 سببه النوع float، فجمع 0.10 و99.99 و210.70 لا يعطي رقماً دقيقاً في التمثيل الثنائي.
  • اسم الملف orders.csv مكتوب داخل الكود، فلا يمكن تشغيل السكربت على ملف آخر دون تعديله.

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

النسخة الثانية Version 2: خمسة طلبات صغيرة

هذه النسخة تضيف الطلبات الخمسة من القصة: الضريبة بالخيار --vat، وتجاهل الملغي وخصم المرتجع، وتحويل الدولار بسعر 3.75، وتصفية الفرع بالخيار --branch، والكتابة إلى ملف CSV بالخيار --csv. وكل إضافة كانت بضعة أسطر في المكان الأقرب:

import csv
import sys

# usage: python report.py [--branch online|store] [--vat] [--csv out.csv]
branch = None
vat = False
out = None
i = 1
while i < len(sys.argv):
    if sys.argv[i] == "--branch":
        branch = sys.argv[i + 1]
        i += 2
    elif sys.argv[i] == "--vat":
        vat = True
        i += 1
    elif sys.argv[i] == "--csv":
        out = sys.argv[i + 1]
        i += 2
    else:
        print("unknown option", sys.argv[i])
        sys.exit(1)

totals = {}
for row in csv.DictReader(open("orders.csv")):
    if branch and row["branch"] != branch:
        continue
    month = row["date"][:7]
    amount = float(row["amount"])
    if row["status"] == "cancelled":
        continue
    elif row["status"] == "refund":
        totals[month] = totals.get(month, 0) - amount
        continue
    if row["currency"] == "USD":
        amount = amount * 3.75
    elif row["currency"] != "SAR":
        print("unknown currency", row["currency"], "in order", row["order_id"])
        continue
    if vat:
        amount = amount * 1.15
    totals[month] = totals.get(month, 0) + amount

if out:
    with open(out, "w") as f:
        f.write("month,total\n")
        for month in sorted(totals):
            f.write(month + "," + str(round(totals[month], 2)) + "\n")
else:
    for month in sorted(totals):
        print(month, round(totals[month], 2))

ونشغلها بلا خيارات، ثم مع الضريبة، ثم لفرع المتجر الإلكتروني، ثم لفرع اسمه خاطئ:

2026-01 630.6
2026-02 365.79
2026-03 950.45
--- --vat
2026-01 725.19
2026-02 446.16
2026-03 1093.02
--- --branch online
2026-01 330.6
2026-02 305.09
2026-03 450.25
--- --branch web
exit=0

والنتيجة تبدو معقولة لمن يقرؤها، ولكن لنحسب فبراير يدوياً من ملف الطلبات: الطلبات المدفوعة هي 210.70 و99.99 و0.10 و60 دولاراً، أي 225 ريالاً، والمجموع 535.79، والمرتجعان هما 20 دولاراً، أي 75 ريالاً، و150 ريالاً، والمجموع 225، فالصافي الصحيح هو 310.79، بينما يطبع السكربت 365.79. والفرق 55 ريالاً هو بالضبط الفرق بين 75 ريالاً و20، أي أن المرتجع بالدولار خصم كأنه بالريال. والسبب في هذه الأسطر:

    elif row["status"] == "refund":
        totals[month] = totals.get(month, 0) - amount
        continue
    if row["currency"] == "USD":
        amount = amount * 3.75

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

قياس النسختين: الأدوات لم تر شيئاً

الآن نقيس النسخ بالأدوات نفسها، والسكربت metrics.sh يمر على كل Tag ويشغل Radon وlizard وpytest:

docker run --rm -v sw1-se-work:/work -v "$PWD:/lab" sw1-se:lab sh /lab/metrics.sh

وهذا جزء من المخرج للنسختين الأوليين:

===== v1
-- python lines (code only):
    LOC: 9
    SLOC: 7
-- radon cc:
-- lizard:
==========================================================================================
Total nloc   Avg.NLOC  AvgCCN  Avg.token   Fun Cnt  Warning cnt   Fun Rt   nloc Rt
------------------------------------------------------------------------------------------
         7       0.0     0.0        0.0        1            0      0.00    0.00
-- tests:
no tests
===== v2
-- python lines (code only):
    LOC: 50
    SLOC: 46
-- radon cc:
-- lizard:
==========================================================================================
Total nloc   Avg.NLOC  AvgCCN  Avg.token   Fun Cnt  Warning cnt   Fun Rt   nloc Rt
------------------------------------------------------------------------------------------
        46       0.0     0.0        0.0        1            0      0.00    0.00
-- tests:
no tests

وهنا مشكلة حقيقية ظهرت في التجربة: Radon لم يطبع أي شيء للنسختين، وlizard أعطى متوسط تعقيد 0.0، وكأن السكربت الذي فيه 16 مساراً بسيط جداً. والسبب أن أدوات التعقيد تقيس الدوال Functions والكلاسات، والسكربت كله مكتوب في المستوى الأعلى من الملف دون أي دالة، فلا تجد الأداة شيئاً تقيسه. وهذه ملاحظة مهمة لمن يضع حداً للتعقيد في خط CI: الكود الذي لا دوال فيه يمر من الحد دائماً. لذلك نلف جسم السكربت كما هو داخل دالة main() دون أي تعديل آخر، ونقيس مرة أخرى بالسكربت wrap-main.sh:

== v1 wrapped in main()
/tmp/v1_main.py
    F 4:0 main - A (3)
------------------------------------------------
       7      3     69      0       9 main@4-12@/tmp/v1_main.py
1 file analyzed.
==============================================================
== v2 wrapped in main()
/tmp/v2_main.py
    F 4:0 main - C (16)
------------------------------------------------
      45     16    326      0      49 main@4-52@/tmp/v2_main.py
1 file analyzed.
==============================================================
== maintainability index per tag
v1:
report.py - A (75.16)
v2:
report.py - A (52.36)
v3:
salesreport/money.py - A (63.40)
salesreport/report.py - A (59.05)
salesreport/__init__.py - A (100.00)
salesreport/cli.py - A (64.48)
salesreport/orders.py - A (61.89)

في المخرج أعلاه لاحظ التالي:

  • التعقيد الدوري للنسخة الأولى 3، وللثانية 16، فخمسة طلبات صغيرة رفعت عدد المسارات أكثر من خمسة أضعاف، وأخرجت الدالة من الفئة A إلى الفئة C.
  • عمود lizard الثاني هو التعقيد CCN، والرابع عدد المعاملات، والأول عدد الأسطر، والدالة صارت 45 سطراً.
  • مؤشر قابلية الصيانة نزل من 75.16 إلى 52.36، وما زال في الفئة A عند Radon لأن حدودها واسعة، لذلك قارن الرقم بنفسه عبر الزمن ولا تنظر إلى الحرف وحده.

النسخة الثالثة Version 3: وحدة Module مختبرة

في هذه النسخة نقسم الكود حسب القرارات التي يحتمل أن تتغير، كما في فكرة Parnas، فيصبح المستودع كما يلي:

.github/workflows/ci.yml   خط CI
pyproject.toml             إعداد pytest وRuff
requirements-dev.txt       نسخ أدوات التطوير
orders.csv
salesreport/
    money.py               العملات والضريبة والتقريب
    orders.py              قراءة ملف الطلبات والتحقق منه
    report.py              حساب المجموع لكل شهر
    cli.py                 الخيارات والطباعة والملفات
tests/
    test_money.py  test_report.py  test_cli.py

والصورة التالية تقارن شكل النسخ الثلاث:

ثلاثة أعمدة: النسخة الأولى ملف واحد من 9 أسطر بلا اختبارات، والنسخة الثانية ملف واحد من 50 سطراً بتعقيد 16 وخطأ في المرتجع بالدولار، والنسخة الثالثة أربعة ملفات صغيرة لكل منها مسؤولية وثلاثة ملفات اختبار و12 اختباراً وخط CI
النسخة الثالثة أطول بالأسطر، ولكن كل قرار فيها له مكان واحد واختبار يحميه

ملف المال يجمع كل قرار يخص المال في مكان واحد، فسعر الصرف ونسبة الضريبة وطريقة التقريب كلها هنا، ويستخدم Decimal بدلاً من float:

"""Money rules: currency conversion, VAT and rounding, all in Decimal."""
from decimal import Decimal, ROUND_HALF_UP

RATES_TO_SAR = {"SAR": Decimal("1"), "USD": Decimal("3.75")}
VAT_RATE = Decimal("0.15")
CENT = Decimal("0.01")


def to_sar(amount: Decimal, currency: str) -> Decimal:
    if currency not in RATES_TO_SAR:
        raise ValueError(f"unknown currency: {currency}")
    return amount * RATES_TO_SAR[currency]


def with_vat(amount: Decimal) -> Decimal:
    return amount * (1 + VAT_RATE)


def round_sar(amount: Decimal) -> Decimal:
    return amount.quantize(CENT, rounding=ROUND_HALF_UP)

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

"""The report itself: pure functions, no files, no printing."""
from collections import defaultdict
from decimal import Decimal

from .money import round_sar, to_sar, with_vat
from .orders import Order

SIGN = {"paid": 1, "refund": -1, "cancelled": 0}


def order_value(order: Order, vat: bool) -> Decimal:
    value = to_sar(order.amount, order.currency) * SIGN[order.status]
    return with_vat(value) if vat else value


def monthly_totals(orders: list[Order], branch: str | None = None,
                   vat: bool = False) -> dict[str, Decimal]:
    totals: dict[str, Decimal] = defaultdict(Decimal)
    for order in orders:
        if branch is None or order.branch == branch:
            totals[order.month] += order_value(order, vat)
    return {month: round_sar(total) for month, total in sorted(totals.items())}

وملف قراءة الطلبات يرفض الحالة غير المعروفة والمبلغ غير الصالح برسالة فيها رقم الطلب، بدلاً من أن يتجاهلها، وملف cli.py يستخدم argparse بدلاً من قراءة sys.argv يدوياً، وكلاهما كامل في مجلد التجربة. أما الاختبارات فكل منها جملة تقرأ كمتطلب، ومنها الاختبار الذي كان سيمنع خطأ فبراير:

from decimal import Decimal

from salesreport.orders import Order
from salesreport.report import monthly_totals


def order(amount, status="paid", currency="SAR", branch="online", month="2026-02"):
    return Order("x", month, branch, currency, Decimal(amount), status)


def test_paid_orders_add_up_without_float_noise():
    assert monthly_totals([order("0.10"), order("0.20")]) == {"2026-02": Decimal("0.30")}


def test_cancelled_orders_count_zero():
    assert monthly_totals([order("100"), order("89.90", "cancelled")]) == {"2026-02": Decimal("100.00")}


def test_usd_refund_is_converted_before_it_is_subtracted():
    orders = [order("60.00", currency="USD"), order("20.00", "refund", currency="USD")]
    assert monthly_totals(orders) == {"2026-02": Decimal("150.00")}


def test_refund_includes_vat_when_the_report_does():
    orders = [order("100.00"), order("100.00", "refund")]
    assert monthly_totals(orders, vat=True) == {"2026-02": Decimal("0.00")}


def test_branch_filter_keeps_only_that_branch():
    orders = [order("10", branch="online"), order("99", branch="store")]
    assert monthly_totals(orders, branch="online") == {"2026-02": Decimal("10.00")}

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

from pathlib import Path

from salesreport.cli import main

SAMPLE = Path(__file__).parent.parent / "orders.csv"


def test_report_for_the_sample_export(capsys):
    assert main([str(SAMPLE)]) == 0
    assert capsys.readouterr().out.splitlines() == [
        "2026-01 630.60",
        "2026-02 310.79",
        "2026-03 950.45",
    ]


def test_csv_output_with_vat(tmp_path):
    out = tmp_path / "report.csv"
    main([str(SAMPLE), "--vat", "--csv", str(out)])
    assert out.read_text().splitlines()[2] == "2026-02,357.41"

والقياس نفسه للنسخة الثالثة أعطى المخرج التالي، وحذفنا منه سطور ملفات الاختبار لأنها كلها في الفئة A:

===== v3
-- python lines (code only):
    LOC: 180
    SLOC: 123
-- radon cc:
salesreport/money.py
    F 9:0 to_sar - A (2)
    F 15:0 with_vat - A (1)
    F 19:0 round_sar - A (1)
salesreport/report.py
    F 16:0 monthly_totals - A (5)
    F 11:0 order_value - A (2)
salesreport/cli.py
    F 9:0 main - A (4)
salesreport/orders.py
    F 20:0 parse_orders - A (4)
    C 11:0 Order - A (1)
...
19 blocks (classes, functions, methods) analyzed.
Average complexity: A (2.1578947368421053)
-- lizard:
==========================================================================================
Total nloc   Avg.NLOC  AvgCCN  Avg.token   Fun Cnt  Warning cnt   Fun Rt   nloc Rt
------------------------------------------------------------------------------------------
       123       4.5     1.7       49.0       18            0      0.00    0.00
-- tests:
12 passed in 0.08s

والنتيجة أن الأسطر زادت من 46 إلى 123 سطر كود، نصفها تقريباً اختبارات، بينما نزل أكبر تعقيد لدالة من 16 إلى 5، وصار متوسط التعقيد 1.7، و12 اختباراً تعمل في أقل من 0.1 ثانية. وتشغيل النسخة الثالثة على ملف الطلبات يعطي فبراير صحيحاً، ويرفض الفرع الخاطئ:

2026-01 630.60
2026-02 310.79
2026-03 950.45
usage: cli.py [-h] [--branch {online,store}] [--vat] [--csv OUT] orders_file
cli.py: error: argument --branch: invalid choice: 'web' (choose from 'online', 'store')
exit=2

ولاحظ هنا قانون Hyrum الذي ذكرناه في البداية، فالنسخة الثانية كانت تطبع 630.6 والثالثة تطبع 630.60، وإذا كان أحد يقرأ هذا المخرج بأداة أخرى فهذا تغيير يجب أن يذكر في ملاحظات الإصدار، كما شرحنا في مقال الإصدارات مع SemVer.

خط CI محلياً مع act

ملف الخط بصيغة GitHub Actions ويعمل كما هو على Gitea Actions وForgejo، وفيه أربع خطوات: جلب الكود، وتثبيت الأدوات، والتدقيق، والاختبارات مع حد أدنى للتغطية 90%:

name: ci
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r requirements-dev.txt
      - run: ruff check .
      - run: pytest --cov=salesreport --cov-fail-under=90

ولا نحتاج GitHub لتشغيله، فأداة act تقرأ ملفات الخط وتشغل كل Job داخل Container على جهازك. ونشغل act نفسها داخل Container صغير من debian:trixie-slim فيه الإصدار 0.2.98، ونعطيه Socket الخاص بـ Docker حتى ينشئ Container الـ Job:

FROM debian:trixie-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl git && rm -rf /var/lib/apt/lists/* \
 && curl -sL https://github.com/nektos/act/releases/download/v0.2.98/act_Linux_x86_64.tar.gz | tar -xz -C /usr/local/bin act
WORKDIR /work/repo
#!/bin/sh
# Runs the GitHub Actions workflow of /work/repo locally with act, in a job container made from sw1-se:lab.
docker run --rm --name sw1-act -v /var/run/docker.sock:/var/run/docker.sock -v sw1-se-work:/work \
  sw1-act:0.2.98 act push -P ubuntu-latest=sw1-se:lab --pull=false --rm "$@"

في الأمر أعلاه لاحظ التالي:

  • الخيار -P ubuntu-latest=sw1-se:lab يخبر act أن يشغل كل Job مكتوب عليه ubuntu-latest داخل الـ Image التي بنيناها، بدلاً من Image كبيرة تحاكي سيرفر GitHub.
  • الخيار --pull=false يمنعه من محاولة تنزيل هذه الـ Image من الإنترنت، لأنها موجودة محلياً فقط.
  • الخيار --rm يحذف Container الـ Job بعد انتهائه حتى لو فشل، ففي أول تشغيل دونه بقي Container باسم يبدأ بـ act-ci-test يعمل بعد فشل الخط، ومعه Volume خاص به، وحذفناهما يدوياً.

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

[ci/test] ⭐ Run Main actions/checkout@v4
[ci/test]   🐳  docker cp src=/work/repo/. dst=/work/repo
[ci/test]   ✅  Success - Main actions/checkout@v4 [69.722731ms]
...
[ci/test] ⭐ Run Main ruff check .
[ci/test]   | I001 [*] Import block is un-sorted or un-formatted
[ci/test]   |  --> salesreport/money.py:2:1
...
[ci/test]   | E501 Line too long (104 > 100)
[ci/test]   |   --> tests/test_report.py:16:101
...
[ci/test]   | Found 2 errors.
[ci/test]   | [*] 1 fixable with `--fix`.
[ci/test]   ❌  Failure - Main ruff check . [177.017123ms]
[ci/test] exitcode '1': failure
...
[ci/test] 🏁  Job failed

في المخرج أعلاه لاحظ التالي:

  • خطوة actions/checkout@v4 لم تنزل شيئاً من GitHub، فـ act يتعرف عليها وينسخ المستودع المحلي إلى الـ Container بالأمر docker cp.
  • الخطأ الأول ترتيب Imports، فالقاعدة I001 تريد ROUND_HALF_UP قبل Decimal، وRuff يقول إنه يستطيع إصلاحه بالخيار --fix.
  • الخطأ الثاني سطر في الاختبارات طوله 104 والحد في pyproject.toml هو 100.
  • الخط توقف عند أول خطوة فاشلة ولم يشغل الاختبارات، وهذا سلوك مقصود: لا فائدة من اختبار كود لم يمر من المدقق.

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

[ci/test] ⭐ Run Main ruff check .
[ci/test]   | All checks passed!
[ci/test]   ✅  Success - Main ruff check . [167.454912ms]
[ci/test] ⭐ Run Main pytest --cov=salesreport --cov-fail-under=90
[ci/test]   | collected 12 items
[ci/test]   |
[ci/test]   | tests/test_cli.py ..                                                     [ 16%]
[ci/test]   | tests/test_money.py .....                                                [ 58%]
[ci/test]   | tests/test_report.py .....                                               [100%]
...
[ci/test]   | Name                      Stmts   Miss  Cover
[ci/test]   | ---------------------------------------------
[ci/test]   | salesreport/__init__.py       0      0   100%
[ci/test]   | salesreport/cli.py           22      1    95%
[ci/test]   | salesreport/money.py         12      0   100%
[ci/test]   | salesreport/orders.py        24      3    88%
[ci/test]   | salesreport/report.py        14      0   100%
[ci/test]   | ---------------------------------------------
[ci/test]   | TOTAL                        72      4    94%
[ci/test]   | Required test coverage of 90% reached. Total coverage: 94.44%
[ci/test]   | ============================== 12 passed in 0.20s ==============================
[ci/test]   ✅  Success - Main pytest --cov=salesreport --cov-fail-under=90 [1.144856212s]
[ci/test] 🏁  Job succeeded

والتغطية 94%، والأسطر الثلاثة غير المغطاة في orders.py هي رسائل الرفض للحالة والمبلغ غير الصالحين، أي أن تقرير التغطية أخبرنا بالضبط بالاختبار الذي ما زال ينقصنا.

ماذا لو جاء طلب جديد؟ What If: دعم اليورو

الآن نأتي إلى ما صنعت النسخة الثالثة من أجله: طلب جديد بعد أشهر، وهو قبول الطلبات باليورو. والتعديل السريع الذي يكتبه أي مطور هو سطر في قاموس الأسعار مع اختبار جديد، والسكربت whatif-eur.sh يضيفهما كما يلي:

RATES_TO_SAR = {"SAR": Decimal("1"), "USD": Decimal("3.75"), "EUR": 4.35}


def test_eur_is_converted():
    assert round_sar(to_sar(Decimal("10.00"), "EUR")) == Decimal("43.50")

وسعر 4.35 هنا مثال وليس سعر صرف حقيقياً. ونشغل الخط:

[ci/test]   | tests/test_money.py .F...F                                               [ 61%]
...
[ci/test]   | ______________________ test_unknown_currency_is_rejected _______________________
[ci/test]   |
[ci/test]   |     def test_unknown_currency_is_rejected():
[ci/test]   |         with pytest.raises(ValueError, match="EUR"):
[ci/test]   | >           to_sar(Decimal("10"), "EUR")
...
[ci/test]   | E       TypeError: unsupported operand type(s) for *: 'decimal.Decimal' and 'float'
...
[ci/test]   | FAILED tests/test_money.py::test_unknown_currency_is_rejected - TypeError: unsupported operand type(s) for *: 'decimal.Decimal' and 'float'
[ci/test]   | FAILED tests/test_money.py::test_eur_is_converted - TypeError: unsupported operand type(s) for *: 'decimal.Decimal' and 'float'
[ci/test]   | ========================= 2 failed, 11 passed in 0.27s =========================
[ci/test]   ❌  Failure - Main pytest --cov=salesreport --cov-fail-under=90 [1.301724064s]
[ci/test] 🏁  Job failed

في المخرج أعلاه لاحظ التالي:

  • الخطأ الأول خطأ نوع حقيقي، فكتابة 4.35 دون Decimal جعلت السعر float، وPython يرفض ضرب Decimal في float بدلاً من أن يعطي رقماً غير دقيق بصمت. ولو حدث هذا في النسخة الثانية التي تستخدم float في كل مكان لما ظهر أي خطأ، ولظهرت أرقام بكسور عشرية طويلة في التقرير.
  • الخطأ الثاني أطرف، فالاختبار القديم test_unknown_currency_is_rejected كان يستخدم اليورو مثالاً على عملة غير معروفة، والآن صار اليورو معروفاً. وهذا ما يعنيه أن الاختبار متطلب مكتوب: عندما تغير المتطلب تغير الاختبار الذي يعبر عنه، والخط أخبرنا بذلك بدلاً من أن نكتشفه بعد سنة.
  • الاختبارات الأحد عشر الأخرى نجحت، أي أن الدولار والضريبة والمرتجعات والفروع لم تتأثر بالتعديل، وهذه هي الحماية التي لم تكن موجودة في النسخة الثانية.

والإصلاح سطران: السعر بالنوع Decimal، والاختبار القديم يستخدم الين الياباني JPY مثالاً على عملة غير معروفة:

-RATES_TO_SAR = {"SAR": Decimal("1"), "USD": Decimal("3.75"), "EUR": 4.35}
+RATES_TO_SAR = {"SAR": Decimal("1"), "USD": Decimal("3.75"), "EUR": Decimal("4.35")}
...
 def test_unknown_currency_is_rejected():
-    with pytest.raises(ValueError, match="EUR"):
-        to_sar(Decimal("10"), "EUR")
+    with pytest.raises(ValueError, match="JPY"):
+        to_sar(Decimal("10"), "JPY")

وبعده نجح الخط بثلاثة عشر اختباراً وتغطية 94%. وتاريخ المستودع كله، كما يعرضه الأمر git log --oneline --shortstat، يبين حجم كل خطوة:

4281168 EUR rate as Decimal; unknown-currency test uses JPY
 2 files changed, 3 insertions(+), 3 deletions(-)
35479d1 Support EUR orders
 2 files changed, 5 insertions(+), 1 deletion(-)
bb7ca4a Fix lint: import order, long line
 2 files changed, 3 insertions(+), 2 deletions(-)
96e08df v3: salesreport package, tests and CI
 13 files changed, 210 insertions(+), 50 deletions(-)
add9548 v2: VAT, refunds, USD, branch filter, CSV output
 1 file changed, 44 insertions(+), 3 deletions(-)
74f2686 v1: monthly totals script
 2 files changed, 27 insertions(+)

ولاحظ أن الطلب الجديد كلف ستة أسطر في ملفين، وأن التحويل إلى النسخة الثالثة كلف 210 أسطر مرة واحدة، وهذا هو الاستثمار الذي يتحدث عنه Brooks: الجهد الإضافي يدفع مرة، ويوفر في كل طلب بعده.

والصورة التالية تلخص تشغيلات الخط الأربعة:

أربعة تشغيلات لخط CI على خط زمني: الأول أحمر عند التدقيق بخطأين في الأسلوب، والثاني أخضر بـ 12 اختباراً وتغطية 94%، والثالث أحمر عند الاختبارات بخطأ نوع Decimal مع float واختبار قديم، والرابع أخضر بـ 13 اختباراً
الخط فشل مرتين، وفي المرتين بقي الخطأ خارج الفرع الرئيسي

مشكلة صغيرة ظهرت في الطريق: ملفات __pycache__ داخل Commit

في أول تنفيذ للتجربة لم يكن في النسخة الثالثة ملف .gitignore، وكان سكربت القياس قد شغل pytest على المستودع، فلما أضاف سكربت اليورو التعديل بالأمر git add -A دخلت معه ملفات Python المترجمة، وكان مخرج git show --stat كما يلي:

97f5f1d Support EUR orders

 salesreport/__pycache__/__init__.cpython-313.pyc         | Bin 0 -> 197 bytes
 salesreport/__pycache__/cli.cpython-313.pyc              | Bin 0 -> 2294 bytes
 salesreport/__pycache__/money.cpython-313.pyc            | Bin 0 -> 1161 bytes
 salesreport/__pycache__/orders.cpython-313.pyc           | Bin 0 -> 1756 bytes
 salesreport/__pycache__/report.cpython-313.pyc           | Bin 0 -> 1622 bytes
 salesreport/money.py                                     |   2 +-
 tests/__pycache__/test_cli.cpython-313-pytest-9.2.0.pyc  | Bin 0 -> 3864 bytes
 .../__pycache__/test_money.cpython-313-pytest-9.2.0.pyc  | Bin 0 -> 5086 bytes
 .../__pycache__/test_report.cpython-313-pytest-9.2.0.pyc | Bin 0 -> 6533 bytes
 tests/test_money.py                                      |   4 ++++
 10 files changed, 5 insertions(+), 1 deletion(-)

فالتعديل الذي هو خمسة أسطر صار عشرة ملفات، ثمانية منها ملفات ثنائية لا يقرؤها مراجع، وتتغير مع كل نسخة Python. والحل ملف .gitignore من ثلاثة أسطر في النسخة الثالثة يستبعد __pycache__/ و.pytest_cache/ و.coverage، وبعده أصبح Commit اليورو ملفين فقط كما في التاريخ أعلاه. وهذه من الأشياء التي لا يعلمها أحد للمبتدئ لأنها «بديهية»، ثم تجدها في نصف المستودعات.

النتائج في جدول Results

المقياسالنسخة الأولىالنسخة الثانيةالنسخة الثالثة
أسطر الكود SLOC746123 (مع الاختبارات)
عدد الملفات115 كود و3 اختبارات
أكبر تعقيد دوري لدالة316 (الفئة C)5 (الفئة A)
مؤشر قابلية الصيانة75.1652.36من 59.05 إلى 64.48 لكل ملف
الاختباراتلا يوجدلا يوجد12 ثم 13، وتغطية 94%
فبراير بلا ضريبة540.7900000000001365.79310.79 (صحيح)
فرع غير موجودلا يوجد خيارمخرج فارغ ورمز 0رسالة خطأ ورمز 2
كلفة إضافة اليوروغير مقاسةغير مقاسة6 أسطر في ملفين، والخط كشف خطأين
مقارنة بالأعمدة بين النسخ الثلاث: أسطر الكود 7 ثم 46 ثم 125، وأكبر تعقيد 3 ثم 16 ثم 5، والاختبارات 0 ثم 0 ثم 13، وصحة أرقام فبراير خاطئة ثم خاطئة ثم صحيحة
النسخة الثالثة أكبر حجماً، ولكنها أبسط في كل دالة، ومحمية باختبارات، وأرقامها صحيحة

التنظيف Cleanup

docker volume rm sw1-se-work act-toolcache
docker rmi sw1-se:lab sw1-act:0.2.98

والـ Volume المسمى act-toolcache تنشئه act في أول تشغيل لتحفظ فيه الأدوات التي تنزلها الخطوات، فاحذفه إذا لم تعد تستخدم act.

متى لا تحتاج كل هذا؟ When Not to

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

  • شخص غيرك صار يشغله أو يعتمد على مخرجه.
  • صار يعمل بشكل دوري، كل يوم أو كل شهر، وليس مرة واحدة.
  • يحسب مالاً أو يعدل بيانات لا يمكن استرجاعها بسهولة.
  • عدل أكثر من ثلاث مرات، أو عدله أكثر من شخص.
  • أصبحت تخاف من تعديله، وهذه أوضح إشارة.

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

الموقفما يكفي
سكربت لمرة واحدة يكتبه ويشغله شخص واحدكود مقروء، وتشغيل على نسخة من البيانات
سكربت دوري يعتمد عليه غيركGit، واختبار واحد على ملف حقيقي، وREADME بطريقة التشغيل
أداة يعدلها أكثر من شخص أو تحسب مالاًتقسيم إلى وحدات، واختبارات وحدة، ومدقق، وخط CI، ومراجعة لكل طلب دمج
نظام يعيش سنوات ويعمل عليه فريقكل ما سبق، مع متطلبات مكتوبة، وسجل قرارات، ونشر آلي، ومراقبة ومقاييس DORA

أخطاء شائعة Common Mistakes

  • قياس الكود الذي لا دوال فيه: أدوات التعقيد تقيس الدوال، والسكربت المكتوب في المستوى الأعلى من الملف يمر من أي حد، كما رأينا مع Radon وlizard.
  • استخدام float للمال: الأخطاء الصغيرة تتجمع في المجموع، واستخدم Decimal أو أعداداً صحيحة بالهللة، وحدد طريقة التقريب في مكان واحد.
  • الصمت عند المدخل الخاطئ: العملة غير المعروفة والفرع الخاطئ يجب أن يوقفا البرنامج برسالة واضحة، فالمخرج الفارغ برمز 0 أسوأ من الخطأ.
  • اختبارات بعد ظهور الخطأ فقط: اكتب الاختبار من المتطلب وأرقامه المحسوبة يدوياً، وليس بنسخ ما يطبعه الكود الحالي، وإلا ثبت الاختبار الخطأ نفسه.
  • اعتبار اختبار قديم فاشل عقبة: عندما يفشل اختبار بعد تغيير متطلب فاقرأه قبل أن تحذفه، فقد يكون يخبرك بأن المتطلب القديم ما زال يعتمد عليه أحد.
  • إعادة الكتابة الكاملة بلا اختبارات تثبت السلوك القديم: قبل أن تقسم كوداً قديماً اكتب اختباراً يثبت مخرجه الحالي، ثم قرر بوعي أي اختلاف في المخرج هو إصلاح وأيه خطأ جديد.
  • git add -A دون .gitignore: سوف تدخل الملفات المترجمة وملفات البيئة وربما الأسرار إلى المستودع.
  • تطبيق كل الممارسات على كل كود: العملية الثقيلة على سكربت لمرة واحدة تضيع الوقت، والمقياس هو عمر الكود وعدد من يعتمدون عليه.

قائمة تحقق Checklist

  • أعرف كم سوف يعيش هذا الكود، ومن سوف يعدله، وما كلفة الخطأ فيه.
  • المتطلبات مكتوبة مع أمثلة بأرقام، ومنها الحالات الحدية مثل المرتجع والعملة الأخرى.
  • الكود في Git، وفيه .gitignore وREADME يشرح التشغيل.
  • كل قرار يحتمل أن يتغير، مثل الأسعار والضريبة وصيغة الملف، في مكان واحد.
  • المال بالنوع Decimal أو بأعداد صحيحة، والتقريب في دالة واحدة.
  • المدخل الخاطئ يوقف البرنامج برسالة ورمز خروج غير صفري.
  • هناك اختبار يشغل البرنامج على ملف حقيقي ويقارن المخرج بأرقام محسوبة يدوياً.
  • المدقق والاختبارات يعملان في خط CI على كل تعديل، ويمكن تشغيل الخط محلياً.
  • كل تعديل يمر بمراجعة من شخص آخر قبل دمجه.
  • أقيس التعقيد والتغطية عبر الزمن، وأنظر إلى الملفات التي تتغير كثيراً وتعقيدها عال.

ماذا تقرأ بعد ذلك؟ Next Steps

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

دليلالتصميم والمعمارية: أربعة مستويات لنشاط واحدما الفرق بين تصميم البرمجيات ومعماريتها وتصميم الأنظمة ومعمارية المؤسسة، ومن يقرر في كل مستوى وكم يعيش قراره.دليلالبرمجة الكائنية OOP للمبتدئين: الوراثة أم التركيب؟الكائنات والواجهات والوراثة وتعدد الأشكال بمثال واحد بلغتي Python وJava، مع أخطاء المترجم الحقيقية وإعادة هيكلة من الوراثة إلى التركيب والاختبارات نفسها تنجح قبل وبعد.دليلالاقتران Coupling والتماسك Cohesion: كيف تقسم الكود؟ما هو الاقتران والتماسك ودرجاتهما، وكيف تقيسهما بأدوات pydeps وimport-linter وLCOM على متجر صغير ثم تعيد تقسيمه فتنخفض الأرقام والاختبارات نفسها خضراء.دليلمبادئ التصميم Design Principles بأمثلة قبل وبعدلماذا يعطل تعديل صغير في الفاتورة شيئاً في المحاسبة، وكيف تساعدك مبادئ مثل SOLID وDRY على كود يتغير دون مفاجآت.

الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • هندسة البرمجيات هي البرمجة مضروبة في الزمن: السؤال ليس هل يعمل الكود اليوم، وإنما هل يمكن تعديله بأمان بعد سنة ومن شخص آخر.
  • البرنامج الذي يستخدمه غيرك داخل نظام أكبر يكلف قرابة تسعة أضعاف البرنامج الذي يعمل عندك، بحسب Brooks، وأغلب هذا الفرق اختبار وتوثيق وواجهات.
  • أكثر من 80% من الصيانة تحسين وتكييف وليس إصلاحاً، والكود الناجح سوف يطلب منه المزيد دائماً.
  • التعقيد يزيد مع كل طلب صغير إذا لم يعمل أحد على تقليله، كما ارتفع في التجربة من 3 إلى 16، ونزل إلى 5 بالتقسيم.
  • الاختبارات وخط CI هما ما جعل إضافة اليورو ستة أسطر آمنة، وكشف خطأ النوع واختباراً قديماً تغير متطلبه.
  • لا تطبق كل الممارسات على كل كود، وابدأ دائماً باختبار واحد على ملف حقيقي عندما يصبح السكربت شيئاً يعتمد عليه غيرك.

سجل التحديثات Changelog

  • 18 نوفمبر 2026: كتابة المقال، وتنفيذ التجربة على Docker Engine 29.8.0 مع Python 3.13.18 (python:3.13.18-slim) وGit 2.47.3 وpytest 9.2.0 وpytest-cov 7.1.0 وRuff 0.17.5 وRadon 6.0.1 وlizard 1.26.1 وact 0.2.98.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.