> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# الاقتران Coupling والتماسك Cohesion: كيف تقسم الكود؟
- URL: https://arabroot.io/articles/الاقتران-coupling-والتماسك-cohesion-كيف-تقسم-الكود-الى-وحدات/
- Published: 2026-11-18T07:43:30.000Z
- Updated: 2026-11-18T08:41:19.000Z
- Description: ما هو الاقتران والتماسك ودرجاتهما، وكيف تقيسهما بأدوات pydeps وimport-linter وLCOM على متجر صغير ثم تعيد تقسيمه فتنخفض الأرقام والاختبارات نفسها خضراء.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, هندسة البرمجيات والـ Backend, DevOps وCI/CD, الاستضافة الذاتية

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

هذا الشعور له اسمان في هندسة البرمجيات: الاقتران Coupling، ويسميه بعض المراجع الترابط، وهو مقدار اعتماد وحدة على غيرها، والتماسك Cohesion، وهو مقدار ارتباط ما في داخل الوحدة الواحدة ببعضه. وقد عرفنا المصطلحين باختصار في [مقال مبادئ التصميم](https://arabroot.io/articles/%D9%85%D8%A8%D8%A7%D8%AF%D8%A6-%D8%A7%D9%84%D8%AA%D8%B5%D9%85%D9%8A%D9%85-solid-%D9%88-dry-%D9%88-kiss/#coupling-cohesion) بمثال طلب شراء يعدل كود خارجي قائمته، وهذا المقال يأخذهما إلى العمق: من أين جاءا، وما درجات كل منهما، وكيف تقيسهما بأدوات حقيقية بدلاً من الانطباع، وكيف تعيد تقسيم كود موجود فتنخفض الأرقام والاختبارات خضراء قبل وبعد.

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

- تعريف الاقتران والتماسك كما جاءا في ورقة Stevens وMyers وConstantine سنة 1974، ودرجات كل منهما من الأسوأ إلى الأفضل.
- فكرة إخفاء المعلومات Information Hiding التي قدمها Parnas سنة 1972، ولماذا هي المعيار الحقيقي لتقسيم الكود.
- مبادئ الحزم Package Principles عند Robert Martin: الاعتماديات بلا دوائر، ومقياس عدم الاستقرار Instability، واتجاه الاعتماد، ومبادئ تماسك الحزمة.
- كيف تقيس ذلك في Python بأدوات pydeps وimport-linter وlcom وcohesion وRuff، ومتى تخطئ هذه الأدوات.
- تجربة عملية على متجر صغير كتبناه بخمس وحدات: قياس قبل، ثم إعادة تقسيم، ثم قياس بعد، والاختبارات نفسها تنجح في المرتين، مع ما حدث عندما أنشأنا متجرين في برنامج واحد، ثم القياس نفسه على مكتبة requests.
- كيف تبدأ في مشروع قائم: قاعدة بالمخالفات الحالية استثناءات، ثم تحسين تدريجي.

## ما هو الاقتران Coupling وما هو التماسك Cohesion؟

في سنة 1974 نشر W. P. Stevens وG. J. Myers وL. L. Constantine في مجلة IBM Systems Journal ورقة بعنوان [Structured Design](https://doi.org/10.1147/sj.132.0115?ref=arabroot.io)، وهدفها أن تجعل تقسيم البرنامج إلى وحدات قراراً له معايير بدلاً من أن يكون ذوقاً شخصياً. وكانت الفكرة الأساسية فيها أن البرنامج الجيد هو الذي تستطيع أن تعدل أو تختبر أو تفهم كل وحدة فيه بأقل قدر من المعرفة عن الوحدات الأخرى، ولقياس ذلك عرفت الورقة مفهومين:

- **الاقتران Coupling**: قوة العلاقة بين وحدتين، أي كم يجب أن تعرف عن الوحدة الأخرى لكي تفهم هذه أو تعدلها. والهدف اقتران منخفض Low Coupling.
- **التماسك Cohesion**: قوة العلاقة بين عناصر الوحدة الواحدة، أي هل كل ما في الملف أو الكلاس يخدم غرضاً واحداً. والهدف تماسك عال High Cohesion.

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

![في اليمين خمس وحدات فيها عناصر بألوان مختلطة وأسهم كثيرة بينها في الاتجاهين ومنها دوائر، وفي اليسار وحدات كل منها بلون واحد، ووحدة واحدة في الوسط تتصل بكل منها بسهم واحد](https://arabroot.io/content/images/2026/11/coupling-cohesion-01-concepts.webp)

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

### درجات الاقتران Coupling Levels: من الأسوأ إلى الأفضل

لم تكتف أدبيات التصميم المنظم Structured Design بالمفهوم، وإنما رتبت أنواع الاقتران في سلم، بدأ في هذه الورقة ثم اكتمل في كتب Myers وفي كتاب Yourdon وConstantine سنة 1979، وما زال يدرس كما هو. والأمثلة التالية كلها من الكود الذي سوف نقيسه في التجربة:

- **اقتران المحتوى Content Coupling**، وهو الأسوأ: وحدة تقرأ أو تعدل البيانات الداخلية لوحدة أخرى، مثل ملف الطلبات الذي ينقص المخزون بالسطر `inventory._stock[sku] -= qty` متجاوزاً أي قاعدة في ملف المخزون.
- **الاقتران المشترك Common Coupling**: وحدات تشترك في بيانات عامة يعدلها الجميع، مثل القاموس `ORDERS` والقائمة `OUTBOX` على مستوى الملف، وسوف ترى في التجربة ماذا يحدث لهذه البيانات عندما ننشئ متجرين.
- **الاقتران الخارجي External Coupling**: وحدات تعتمد على شيء خارجي بصيغته، مثل صيغة ملف أو بروتوكول جهاز، كالثابت `SMTP_HOST` الذي يقرؤه ملفان.
- **اقتران التحكم Control Coupling**: وحدة تمرر لأخرى علامة Flag تحدد ماذا تفعل، مثل `send(order, mode="sms")`، فالمرسل يعرف تفاصيل منطق المستقبل.
- **اقتران البنية Stamp Coupling**: وحدة تمرر بنية بيانات كاملة والمستقبل يحتاج حقلاً منها، مثل أن يأخذ ملف الفواتير طلباً كاملاً ليقرأ منه المبلغ فقط.
- **اقتران البيانات Data Coupling**، وهو الأفضل: الوحدات تتبادل قيماً بسيطة عبر معاملات، مثل `billing.invoice(order_id, net)` بعد التقسيم.

### درجات التماسك Cohesion Levels

وللتماسك سلم مثله، من الأضعف إلى الأقوى:

- **التماسك العرضي Coincidental**: عناصر لا علاقة بينها إلا أنها في الملف نفسه، وهذا هو ملف `utils.py` الذي فيه الضريبة وإرسال البريد وتاريخ اليوم وتحويل النص إلى رابط.
- **التماسك المنطقي Logical**: عناصر من «النوع» نفسه تختار بينها بعلامة، مثل ملف فيه كل دوال الطباعة لكل الشاشات.
- **التماسك الزمني Temporal**: عناصر تجتمع لأنها تحدث في الوقت نفسه، مثل دالة `startup()` تفتح قاعدة البيانات وتقرأ الإعداد وتمسح الملفات المؤقتة.
- **التماسك الإجرائي Procedural** و**الاتصالي Communicational** و**التسلسلي Sequential**: عناصر تجتمع لأنها خطوات متتالية، أو تعمل على البيانات نفسها، أو يكون مخرج إحداها مدخل الأخرى، وهي درجات مقبولة.
- **التماسك الوظيفي Functional**، وهو الأقوى: كل ما في الوحدة يخدم مهمة واحدة يمكن أن تصفها بجملة، مثل «كل ما يخص المال: الضريبة والتقريب والفواتير».

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

![سلمان متجاوران: سلم الاقتران من المحتوى في الأسفل باللون الأحمر ثم المشترك ثم الخارجي ثم التحكم ثم البنية ثم البيانات في الأعلى باللون الأخضر، وسلم التماسك من العرضي في الأسفل إلى الوظيفي في الأعلى، وبجانب كل درجة مثال من كود المتجر](https://arabroot.io/content/images/2026/11/coupling-cohesion-02-levels.webp)

كلما صعدت في السلمين قلت المعرفة التي تحتاجها عن غير الوحدة التي تعدلها

## إخفاء المعلومات Information Hiding: معيار Parnas

قبل ورقة Stevens بسنتين، نشر David Parnas في مجلة Communications of the ACM في ديسمبر 1972 ورقة On the Criteria to Be Used in Decomposing Systems into Modules، وهي من أكثر الأوراق اقتباساً في المهنة. أخذ Parnas برنامجاً صغيراً يصنع فهرساً للكلمات المفتاحية في سياقها KWIC، وقسمه بطريقتين. الطريقة الأولى، وهي التي يختارها أغلب المبرمجين، تقسم البرنامج حسب خطوات المعالجة: وحدة للقراءة، ووحدة لتدوير الأسطر، ووحدة للترتيب، ووحدة للطباعة، وكل الوحدات تعرف شكل البيانات في الذاكرة. والطريقة الثانية تقسمه حسب القرارات التصميمية التي يحتمل أن تتغير: وحدة تخفي طريقة تخزين الأسطر، ووحدة تخفي طريقة التدوير، وغيرها، وكل وحدة تعرض دوالاً ولا تعرض بياناتها.

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

## مبادئ الحزم Package Principles عند Robert Martin

الأوراق السابقة كانت عن الدوال والوحدات داخل برنامج واحد، وفي التسعينيات نقل Robert C. Martin الفكرة إلى مستوى الحزم Packages والمكونات Components، ونشرها في كتاب [Agile Software Development: Principles, Patterns, and Practices](https://www.informit.com/store/agile-software-development-principles-patterns-and-practices-9780135974445?ref=arabroot.io) سنة 2002، ثم في الجزء الرابع من كتاب [Clean Architecture](https://www.informit.com/store/clean-architecture-a-craftsman-s-guide-to-software-structure-9780134494166?ref=arabroot.io) سنة 2017\. وثلاثة منها عن الاقتران بين المكونات:

- **مبدأ الاعتماديات بلا دوائر Acyclic Dependencies Principle**: رسم الاعتماديات بين الوحدات يجب ألا تكون فيه دائرة، لأن الدائرة تعني أن هذه الوحدات لا يمكن فهمها أو اختبارها أو إصدارها إلا معاً، فهي في الحقيقة وحدة واحدة كبيرة.
- **مبدأ الاعتماديات المستقرة Stable Dependencies Principle**: اعتمد في اتجاه الاستقرار، أي أن الوحدة التي تتغير كثيراً تعتمد على الوحدة التي تتغير قليلاً، وليس العكس.
- **مبدأ التجريد المستقر Stable Abstractions Principle**: الوحدة المستقرة يجب أن تكون مجردة، أي واجهات أكثر من تفاصيل، حتى يمكن توسيعها دون تعديلها.

ولكي تطبق المبدأ الثاني بالأرقام عرف Martin لكل وحدة رقمين بسيطين: عدد الوحدات التي تعتمد عليها، ويسمى الاقتران الوارد Afferent Coupling واختصاراً Ca، وعدد الوحدات التي تعتمد هي عليها، ويسمى الاقتران الصادر Efferent Coupling واختصاراً Ce، ثم عدم الاستقرار Instability:

```text
I = Ce / (Ca + Ce)
```

والقيمة صفر تعني وحدة مستقرة تماماً: كثيرون يعتمدون عليها وهي لا تعتمد على أحد، فتغييرها صعب ومكلف. والقيمة واحد تعني وحدة غير مستقرة: لا يعتمد عليها أحد وهي تعتمد على غيرها، فتغييرها سهل. والمبدأ يقول إن الأسهم يجب أن تذهب من القيم العالية إلى القيم المنخفضة. وفي Java هناك أداة قديمة مشهورة تحسب هذه الأرقام لكل حزمة اسمها [JDepend](https://github.com/clarkware/jdepend?ref=arabroot.io)، أما في Python فسوف نحسبها في التجربة من رسم الاعتماديات الذي تخرجه pydeps، والصورة التالية تبين المبدأ:

![ثلاث طبقات من الوحدات مرتبة حسب عدم الاستقرار: في الأعلى app بقيمة 1.00، وفي الأسفل billing وinventory وnotifications بقيمة 0.00، والأسهم تنزل من الأعلى إلى الأسفل باللون الأخضر، وبجانبها في نسخة ما قبل التقسيم سهم أحمر صاعد من billing بقيمة 0.40 إلى orders بقيمة 0.57](https://arabroot.io/content/images/2026/11/coupling-cohesion-06-instability.webp)

الاعتماد يجب أن ينزل نحو الوحدات المستقرة، والسهم الصاعد علامة على أن وحدة مستقرة صارت تتأثر بتغييرات وحدة أقل استقراراً

### وماذا عن تماسك الحزمة؟ Package Cohesion

وضع Martin ثلاثة مبادئ أخرى للتماسك على مستوى الحزمة، أي ماذا تضع معاً في وحدة واحدة:

- **مبدأ التكافؤ بين الإصدار وإعادة الاستخدام Reuse/Release Equivalence Principle**: ما تعيد استخدامه يجب أن يصدر معاً برقم إصدار واحد، فلا معنى لحزمة نصف دوالها يتبع إصداراً والنصف الآخر يتبع آخر.
- **مبدأ الإغلاق المشترك Common Closure Principle**: اجمع في الوحدة الواحدة الكلاسات التي تتغير للسبب نفسه وفي الوقت نفسه، وافصل ما يتغير لأسباب مختلفة. وهو مبدأ المسؤولية الواحدة SRP مطبقاً على الحزم، وهو ما جعلنا نضع الضريبة والتقريب والفاتورة في ملف واحد، لأن تغيير نسبة الضريبة يغيرها معاً.
- **مبدأ إعادة الاستخدام المشترك Common Reuse Principle**: لا تجبر من يستخدم الوحدة على الاعتماد على أشياء لا يحتاجها، فالوحدة التي تستورد `utils` لتأخذ دالة الضريبة صارت تعتمد أيضاً على إرسال البريد وعلى الثابت `SMTP_HOST`، وأي تغيير فيهما يعني أنها تحتاج اختباراً من جديد.

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

## كيف تقيس الاقتران والتماسك بأدوات حقيقية؟

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

- [**pydeps**](https://github.com/thebjorn/pydeps?ref=arabroot.io): تقرأ جمل الاستيراد Imports وتبني رسم الاعتماديات بين الوحدات، ويمكن أن تخرجه كصورة مع Graphviz، أو كملف JSON بالخيار `--show-deps`، ومنه نحسب Ca وCe وI والدوائر.
- [**import-linter**](https://import-linter.readthedocs.io/en/stable/?ref=arabroot.io): تكتب فيها قواعد Contracts عن من يحق له أن يستورد من، مثل الطبقات Layers والاستقلال Independence والمنع Forbidden، وتفشل إذا خالف الكود قاعدة، فتصلح لخط CI. وهي مبنية على مكتبة [grimp](https://grimp.readthedocs.io/en/stable/?ref=arabroot.io) التي تبني رسم الاستيراد.
- [**lcom**](https://pypi.org/project/lcom/?ref=arabroot.io): تحسب مقياس نقص التماسك في الدوال Lack of Cohesion of Methods بالصيغة LCOM4، وهو عدد المجموعات المنفصلة من الدوال والحقول داخل الكلاس، فالقيمة 1 تعني كلاساً متماسكاً، و4 تعني أن الكلاس فيه أربعة كلاسات صغيرة لا علاقة بينها. وأصل المقياس من مجموعة مقاييس Chidamber وKemerer في ورقة [A Metrics Suite for Object Oriented Design](https://doi.org/10.1109/32.295895?ref=arabroot.io) سنة 1994، ثم عدله Hitz وMontazeri إلى الصيغة الرابعة سنة 1995.
- [**cohesion**](https://github.com/mschwager/cohesion?ref=arabroot.io): تحسب لكل دالة نسبة حقول الكلاس التي تستخدمها، ثم نسبة للكلاس كله، فتعطيك تفصيلاً يبين أي دالة هي الغريبة.
- **Ruff بالقاعدة** [**SLF001**](https://docs.astral.sh/ruff/rules/private-member-access/?ref=arabroot.io): تنبه عند الوصول إلى اسم يبدأ بشرطة سفلية من خارج الكلاس أو الوحدة، وهذا هو اقتران المحتوى بالضبط، ولا تراه أي أداة من أدوات الاستيراد لأن الاستيراد نفسه مسموح.

وفي Java وC# هناك أدوات تكتب القواعد كاختبارات، مثل ArchUnit وNetArchTest، وقد استخدمنا فكرتها في [مقال Clean Architecture](https://arabroot.io/articles/clean-architecture-%D9%88-hexagonal-%D8%A7%D8%AA%D8%AC%D8%A7%D9%87-%D8%A7%D9%84%D8%A7%D8%B9%D8%AA%D9%85%D8%A7%D8%AF%D9%8A%D8%A7%D8%AA/) لنمنع منطق العمل من الاعتماد على قاعدة البيانات.

### الاقتران الذي لا تراه في الكود: الملفات التي تتغير معاً

كل الأدوات السابقة تقرأ الكود في لحظة واحدة، ولكن هناك نوع من الاقتران لا يظهر في جمل الاستيراد أبداً، وهو الملفات التي تتغير معاً في Git. فإذا كان كل تعديل على ملف الفواتير يصاحبه تعديل على قالب البريد، حتى لو لم يستورد أحدهما الآخر، فبينهما اقتران حقيقي عبر معرفة مشتركة، مثل شكل المبلغ أو أسماء الحقول. ويسمى هذا اقتران التغيير Change Coupling أو الاقتران المنطقي Logical Coupling، وتجده بالنظر إلى الملفات التي تظهر معاً في الـ Commits نفسها عبر `git log --name-only`، فإذا تكرر الزوج نفسه كثيراً فهذه إشارة إلى أن بينهما قراراً واحداً موزعاً على مكانين، والحل غالباً أن تنقل هذا القرار إلى مكان واحد، أو أن تجعل الملفين في وحدة واحدة. وهذا النوع مهم بشكل خاص عندما تفكر في فصل وحدتين إلى خدمتين، لأن الملفات التي تتغير معاً سوف تعني نشر خدمتين معاً في كل تعديل.

💡

الاقتران لا يقف عند حدود مشروعك. في 22 مارس 2016 حذف مطور 273 حزمة له من سجل npm، ومنها حزمة صغيرة اسمها left-pad فيها دالة واحدة تضيف مسافات إلى يسار النص. وبحسب [مدونة npm](https://blog.npmjs.org/post/141577284765/kik-left-pad-and-npm?ref=arabroot.io) بدأت بعد الساعة 2:30 ظهراً بتوقيت المحيط الهادئ مئات الأخطاء في الدقيقة، لأن مشاريع كثيرة تعتمد عليها مباشرة أو عبر سلاسل اعتماديات، ومنها Babel وAtom، فتوقف بناؤها. والدرس أن كل اعتماد هو اقتران صادر Ce له كلفة، حتى لو كان سطراً واحداً، فاحسب هذه الكلفة قبل أن تضيفه، وثبت النسخ، واحتفظ بنسخة من الحزم التي يعتمد عليها البناء.

## تجربة عملية Lab: قياس متجر صغير ثم إعادة تقسيمه

في هذه التجربة كتبنا متجراً صغيراً بلغة Python بالطريقة التي يكبر بها الكود عادة: ميزة بعد ميزة في أقرب ملف. وفيه خمس وحدات: المخزون، والفواتير، والبريد، والطلبات، وملف المساعدات `utils.py`، وواجهة عامة واحدة اسمها `Shop` في `app.py` يستخدمها كل من يتعامل مع المتجر. ثم قسنا الاقتران والتماسك، وأعدنا تقسيم الكود، وقسنا مرة أخرى. وكل الأوامر تعمل داخل Container، وملفات التجربة كاملة في مجلد `lab` مع المقال: `before` و`after` والاختبارات وسكربتات القياس.

### التجهيز Setup

```dockerfile
FROM python:3.13.18-slim
RUN pip install --no-cache-dir pytest==9.2.0 pydeps==3.0.9 import-linter==2.16 cohesion==1.2.0 lcom==0.1.0 radon==6.0.1 ruff==0.17.5
WORKDIR /lab
```

```bash
docker build -t sw1-cc:lab .
docker run --rm -v "$PWD:/lab" sw1-cc:lab sh /lab/measure.sh before
```

والسكربت `measure.sh` يشغل الاختبارات، ثم يحسب الاقتران من مخرج pydeps، ثم يفحص القواعد بـ import-linter، ثم يبحث عن الوصول إلى الأسماء الخاصة بـ Ruff، ثم يحسب LCOM4:

```bash
#!/bin/sh
# usage: sh /lab/measure.sh before|after   tests, coupling numbers, contracts, private access, class cohesion
cd /lab/$1
export PYTHONPATH=/lab/$1 PYTHONDONTWRITEBYTECODE=1
echo "== tests";            pytest -q -p no:cacheprovider /lab/tests | tail -1
echo "== coupling (pydeps)"; pydeps shop --show-deps --no-output 2>/dev/null | python /lab/coupling.py
echo "== contracts";        lint-imports --config /lab/importlinter.ini --no-cache | grep -E "KEPT|BROKEN|kept,|not allowed|^- shop"
echo "== private access";   ruff check --no-cache --select SLF001 --output-format concise shop | tail -6
echo "== class cohesion (LCOM4)"; lcom shop | grep -E "shop\.|Average"
```

### الكود قبل التقسيم Before

ملف المساعدات فيه كل ما لم يجد له أحد مكاناً:

```python
"""Shared helpers. Everything that did not have a home ended up here."""
from datetime import date
from decimal import ROUND_HALF_UP, Decimal

VAT_RATE = Decimal("0.15")
SMTP_HOST = "smtp.example.com"
OUTBOX: list[dict] = []          # stands in for the mail server

def money(amount: Decimal) -> Decimal:
    return amount.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)

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

def send_email(to: str, subject: str, body: str) -> None:
    OUTBOX.append({"host": SMTP_HOST, "to": to, "subject": subject, "body": body})

def today() -> str:
    return date(2026, 11, 17).isoformat()

def slugify(text: str) -> str:
    return "-".join(text.lower().split())
```

وملف الفواتير يقرأ جدول الطلبات من ملف الطلبات ويعدل حالة الطلب:

```python
"""Invoices."""
from shop import orders, utils

INVOICES: list[dict] = []

def create_invoice(order_id: int) -> dict:
    order = orders.ORDERS[order_id]               # reads the order table of another module
    total = utils.add_vat(order["net"])
    invoice = {"no": len(INVOICES) + 1, "order_id": order_id, "total": total, "date": utils.today()}
    INVOICES.append(invoice)
    order["status"] = "invoiced"                  # and changes it
    return invoice
```

وملف البريد يقرأ الطلبات والفواتير ليكتب الرسالة:

```python
"""Customer emails."""
from shop import billing, orders, utils

def order_confirmed(order_id: int) -> None:
    order = orders.ORDERS[order_id]
    invoice = next(i for i in billing.INVOICES if i["order_id"] == order_id)
    utils.send_email(order["email"], f"Order {order_id} confirmed",
                     f"Total with VAT: {invoice['total']} SAR")
```

وملف الطلبات هو المركز، وفيه كلاس `OrderManager` الذي كبر مع الوقت:

```python
"""Placing orders."""
from shop import billing, inventory, notifications, utils

ORDERS: dict[int, dict] = {}

class OutOfStock(Exception):
    pass

class OrderManager:
    """Grew one feature at a time: orders, stock, reports, mail settings."""

    def __init__(self):
        self.next_id = 1
        self.daily_count = 0
        self.report_title = "Daily orders"
        self.smtp_retries = 3

    def place(self, email: str, sku: str, qty: int) -> int:
        if inventory._stock.get(sku, 0) < qty:      # reaches into another module's private data
            raise OutOfStock(sku)
        inventory._stock[sku] -= qty
        order_id = self.next_id
        self.next_id += 1
        ORDERS[order_id] = {"email": email, "sku": sku, "qty": qty,
                            "net": inventory._prices[sku] * qty, "status": "new"}
        billing.create_invoice(order_id)
        notifications.order_confirmed(order_id)
        return order_id

    def count_today(self) -> int:
        self.daily_count = sum(1 for o in ORDERS.values() if o["status"] != "cancelled")
        return self.daily_count

    def report_header(self) -> str:
        return f"{self.report_title} {utils.today()}"

    def mail_settings(self) -> dict:
        return {"host": utils.SMTP_HOST, "retries": self.smtp_retries}
```

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

```python
"""Behaviour tests on the public entry point: the same file runs on before/ and after/."""
from decimal import Decimal

import pytest

from shop.app import OutOfStock, Shop

@pytest.fixture
def shop():
    s = Shop()
    s.add_product("KB-1", "200.00", 5)
    return s

def test_order_reduces_stock(shop):
    shop.place_order("a@example.com", "KB-1", 2)
    assert shop.stock("KB-1") == 3

def test_invoice_includes_vat(shop):
    shop.place_order("a@example.com", "KB-1", 2)
    assert shop.invoices()[0]["total"] == Decimal("460.00")

def test_customer_gets_one_email_with_the_total(shop):
    shop.place_order("a@example.com", "KB-1", 1)
    [mail] = shop.sent_emails()
    assert mail["to"] == "a@example.com" and "230.00" in mail["body"]

def test_out_of_stock_changes_nothing(shop):
    with pytest.raises(OutOfStock):
        shop.place_order("a@example.com", "KB-1", 6)
    assert shop.stock("KB-1") == 5 and shop.invoices() == [] and shop.sent_emails() == []
```

### القياس قبل التقسيم

هذا مخرج `measure.sh before`:

```text
== tests
4 passed in 0.35s
== coupling (pydeps)
module                  Ce  Ca      I   imports
shop.app                 4   0   1.00   billing, inventory, orders, utils
shop.billing             2   3   0.40   orders, utils
shop.inventory           1   2   0.33   utils
shop.notifications       3   1   0.75   billing, orders, utils
shop.orders              4   3   0.57   billing, inventory, notifications, utils
shop.utils               0   5   0.00   -
edges: 14
cycles: 3
  billing -> orders -> billing
  billing -> orders -> notifications -> billing
  notifications -> orders -> notifications
impact of a change (modules that import it directly or indirectly):
  app           0  -
  billing       3  app, notifications, orders
  inventory     4  app, billing, notifications, orders
  notifications 3  app, billing, orders
  orders        3  app, billing, notifications
  utils         5  app, billing, inventory, notifications, orders
== contracts
shop layers BROKEN
Contracts: 0 kept, 1 broken.
shop.notifications is not allowed to import shop.billing:
- shop.notifications -> shop.billing (l.2)
shop.billing is not allowed to import shop.orders:
- shop.billing -> shop.orders (l.2)
shop.notifications is not allowed to import shop.orders:
- shop.notifications -> shop.orders (l.2)
== private access
shop/orders.py:21:12: SLF001 Private member accessed: `_stock`
shop/orders.py:23:9: SLF001 Private member accessed: `_stock`
shop/orders.py:27:36: SLF001 Private member accessed: `_prices`
Found 3 errors.
== class cohesion (LCOM4)
| shop.app.Shop            | 1    |
| shop.orders.OrderManager | 4    |
| shop.orders.OutOfStock   | 0    |
| Average                  | 1.67 |
```

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

- الاختبارات الأربعة نجحت، أي أن الكود صحيح من الخارج، وكل المشكلات التالية مشكلات تصميم وليست أخطاء.
- بين ست وحدات 14 سهماً، وثلاث دوائر: الفواتير تستورد الطلبات والطلبات تستورد الفواتير، والبريد يستورد الطلبات والطلبات تستورد البريد. وبحسب مبدأ الاعتماديات بلا دوائر فإن الفواتير والطلبات والبريد هي في الحقيقة وحدة واحدة كبيرة.
- `utils` قيمتها I تساوي 0.00 و5 وحدات تعتمد عليها، فهي أكثر وحدة مستقرة في المتجر، أي أصعبها تغييراً، مع أنها أقلها تماسكاً.
- الفواتير بقيمة 0.40 تعتمد على الطلبات بقيمة 0.57، أي أن السهم يصعد من الأكثر استقراراً إلى الأقل، وهذا مخالف لمبدأ الاعتماديات المستقرة.
- قسم الأثر يجيب عن سؤال المراجع: إذا عدلت الفواتير فإن ثلاث وحدات قد تتأثر، وإذا عدلت المخزون فأربع، وإذا عدلت `utils` فكل المتجر.
- القاعدة التي كتبناها لـ import-linter، وهي أن الواجهة تستخدم الطلبات، والطلبات تستخدم الوحدات الثلاث، والثلاث لا تعرف بعضها، مخالفة في ثلاثة استيرادات، وكل سطر يذكر الملف ورقم السطر.
- Ruff وجد ثلاثة أماكن يصل فيها ملف الطلبات إلى `_stock` و`_prices` داخل المخزون، وهذا اقتران المحتوى الذي لم تره أي أداة استيراد.
- LCOM4 للكلاس `OrderManager` يساوي 4، أي أن فيه أربع مجموعات منفصلة: الطلبات، والعد اليومي، وعنوان التقرير، وإعداد البريد.

وقاعدة import-linter التي استخدمناها ملف صغير:

```ini
[importlinter]
root_package = shop

[importlinter:contract:layers]
name = shop layers
type = layers
layers =
    shop.app
    shop.orders
    shop.billing | shop.inventory | shop.notifications
```

والشرطة العمودية في السطر الأخير تعني أن الوحدات الثلاث في الطبقة نفسها، وأنها مستقلة لا يستورد بعضها بعضاً، كما يشرح [توثيق أنواع القواعد](https://import-linter.readthedocs.io/en/stable/contract%5Ftypes/?ref=arabroot.io). والأداة cohesion تعطي تفصيلاً أدق لكل دالة في `OrderManager`:

```text
  Class: OrderManager (11:0)
    Function: __init__ 4/4 100.00%
    Function: place 1/4 25.00%
    Function: count_today 1/4 25.00%
    Function: report_header 1/4 25.00%
    Function: mail_settings 1/4 25.00%
    Total: 40.0%
```

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

### ماذا لو أنشأنا متجرين؟ What If: الاقتران المشترك

قبل التقسيم جربنا سيناريو يحدث فعلاً في المشاريع: الواجهة الويب تريد أن تخدم متجرين في البرنامج نفسه، أو تشغيل اختبارين بالتوازي، فتنشئ كائني `Shop`:

```python
# What if the web layer creates a second Shop, for a second store or a test running next to another?
from shop.app import Shop

a = Shop()
a.add_product("KB-1", "200.00", 5)
b = Shop()
b.add_product("KB-1", "200.00", 1)

a.place_order("a@example.com", "KB-1", 1)
print("stock in a:", a.stock("KB-1"), "| stock in b:", b.stock("KB-1"))
print("invoices in a:", len(a.invoices()), "| invoices in b:", len(b.invoices()))
```

والمخرج قبل التقسيم:

```text
stock in a: 0 | stock in b: 0
invoices in a: 1 | invoices in b: 1
```

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

![قبل التقسيم: كائنان Shop a وShop b يشيران إلى المتغيرات العامة نفسها _stock وORDERS وINVOICES وOUTBOX في الملفات، فمخزون الاثنين صفر وفاتورة a ظهرت في b. وبعد التقسيم: كل Shop يملك Inventory وBilling وMailer خاصة به، فمخزون a أربعة ومخزون b واحد](https://arabroot.io/content/images/2026/11/coupling-cohesion-07-two-shops.webp)

الاقتران المشترك: البيانات على مستوى الملف يتشاركها كل من يستورده، حتى لو أنشأت كائنين

وقد يتساءل البعض: كيف أكتشف هذا النوع من الاقتران في مشروعي قبل أن يظهر في الإنتاج؟ والإجابة في ثلاث علامات. الأولى أن تبحث عن متغيرات على مستوى الملف تتغير قيمتها، أي قواميس وقوائم تعدل بعد الاستيراد، وليس ثوابت. والثانية أن تجد في الاختبارات دوالاً تمسح حالة عامة قبل كل اختبار، مثل المنشئ `Shop()` هنا الذي يمسح القوائم العامة، فهذا اعتراف بأن الحالة مشتركة. والثالثة أن تشغل الاختبارات بترتيب عشوائي أو بالتوازي، فالاختبار الذي ينجح وحده ويفشل مع غيره علامة شبه مؤكدة على حالة مشتركة، كما رأينا في تجربة الترتيب العشوائي في [مقال اختبارات الوحدة](https://arabroot.io/articles/%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1%D8%A7%D8%AA-%D8%A7%D9%84%D9%88%D8%AD%D8%AF%D8%A9-unit-tests-%D8%B9%D9%85%D9%84%D9%8A%D8%A7-%D9%88%D9%85%D8%AA%D9%89-%D8%AA%D8%B3%D8%AA%D8%AE%D8%AF%D9%85-mocks/#isolation).

### إعادة التقسيم Refactoring خطوة خطوة

أعدنا تقسيم المتجر بخمس خطوات، وبعد كل خطوة كانت الاختبارات تعمل:

1. **إخفاء المخزون**: صار المخزون كلاساً يملك بياناته، وأضفنا له دالة `reserve` تتحقق من الكمية وتنقصها وترجع سعر السطر، فلم يعد أحد يحتاج `_stock`. وهذه هي فكرة Parnas: القرار المخفي هو طريقة حفظ الكميات.
2. **فك الدائرة بين الطلبات والفواتير**: الفواتير لم تعد تقرأ جدول الطلبات، وإنما تستقبل البيانات التي تحتاجها، أي رقم الطلب والمبلغ الصافي، وترجع الفاتورة، ومن يملك الطلب يغير حالته. وهذا انتقال من اقتران المحتوى إلى اقتران البيانات.
3. **البريد لا يعرف الطلبات**: صار `Mailer` يستقبل العنوان والرقم والمبلغ، ولا يستورد أي وحدة من المتجر.
4. **الطلبات تعتمد على واجهات**: خدمة الطلبات تعرف بروتوكولين صغيرين `Stock` و`Invoicer` ودالة للتأكيد، ولا تستورد المخزون ولا الفواتير ولا البريد، وهذا عكس الاعتماديات Dependency Inversion.
5. **حذف utils**: الضريبة والتقريب ذهبا إلى الفواتير، والبريد ذهب إلى `Mailer`، وتاريخ اليوم صار معاملاً للفواتير، وتحويل النص إلى رابط حذف لأنه لم يكن يستخدمه أحد غير المخزون في دالة لم يستدعها أحد.

ملف الطلبات بعد التقسيم:

```python
"""Placing orders: the one place that coordinates stock, billing and the email."""
from dataclasses import dataclass
from decimal import Decimal
from typing import Callable, Protocol

class Stock(Protocol):
    def reserve(self, sku: str, qty: int) -> Decimal: ...

class Invoicer(Protocol):
    def invoice(self, order_id: int, net: Decimal): ...

@dataclass
class Order:
    order_id: int
    email: str
    sku: str
    qty: int
    status: str = "new"

class OrderService:
    def __init__(self, stock: Stock, billing: Invoicer,
                 on_confirmed: Callable[[str, int, Decimal], None]):
        self._stock = stock
        self._billing = billing
        self._on_confirmed = on_confirmed
        self._orders: dict[int, Order] = {}

    def place(self, email: str, sku: str, qty: int) -> int:
        net = self._stock.reserve(sku, qty)            # raises OutOfStock before anything changes
        order = Order(len(self._orders) + 1, email, sku, qty)
        self._orders[order.order_id] = order
        invoice = self._billing.invoice(order.order_id, net)
        order.status = "invoiced"
        self._on_confirmed(email, order.order_id, invoice.total)
        return order.order_id

    def count_open(self) -> int:
        return sum(1 for o in self._orders.values() if o.status != "cancelled")
```

وملف المخزون:

```python
"""Stock levels and prices. Other modules ask; only this module changes the numbers."""
from decimal import Decimal

class OutOfStock(Exception):
    pass

class Inventory:
    def __init__(self):
        self._stock: dict[str, int] = {}
        self._prices: dict[str, Decimal] = {}

    def add_product(self, sku: str, price: Decimal, qty: int) -> None:
        self._prices[sku] = price
        self._stock[sku] = qty

    def stock(self, sku: str) -> int:
        return self._stock.get(sku, 0)

    def reserve(self, sku: str, qty: int) -> Decimal:
        """Takes qty out of stock and returns the net price of the line."""
        if self.stock(sku) < qty:
            raise OutOfStock(sku)
        self._stock[sku] -= qty
        return self._prices[sku] * qty
```

والواجهة العامة هي الوحدة الوحيدة التي تعرف كل الوحدات، وتربطها ببعض، وهذا ما يسمى جذر التركيب Composition Root:

```python
"""The public entry point: the only module that knows all the others and wires them together."""
from dataclasses import asdict
from datetime import date
from decimal import Decimal

from shop.billing import Billing
from shop.inventory import Inventory, OutOfStock
from shop.notifications import Mailer
from shop.orders import OrderService

__all__ = ["Shop", "OutOfStock"]

class Shop:
    def __init__(self, today: date = date(2026, 11, 17), smtp_host: str = "smtp.example.com"):
        self._inventory = Inventory()
        self._billing = Billing(today)
        self._mailer = Mailer(smtp_host)
        self._orders = OrderService(self._inventory, self._billing, self._mailer.order_confirmed)

    def add_product(self, sku: str, price: str, qty: int) -> None:
        self._inventory.add_product(sku, Decimal(price), qty)

    def place_order(self, email: str, sku: str, qty: int) -> int:
        return self._orders.place(email, sku, qty)

    def stock(self, sku: str) -> int:
        return self._inventory.stock(sku)

    def invoices(self) -> list[dict]:
        return [asdict(i) for i in self._billing.invoices()]

    def sent_emails(self) -> list[dict]:
        return list(self._mailer.outbox)
```

أما الفواتير والبريد فهما في مجلد التجربة، ولا يستورد أي منهما شيئاً من المتجر.

### القياس بعد التقسيم

```text
== tests
4 passed in 0.19s
== coupling (pydeps)
module                  Ce  Ca      I   imports
shop.app                 4   0   1.00   billing, inventory, notifications, orders
shop.billing             0   1   0.00   -
shop.inventory           0   1   0.00   -
shop.notifications       0   1   0.00   -
shop.orders              0   1   0.00   -
edges: 4
cycles: 0
impact of a change (modules that import it directly or indirectly):
  app           0  -
  billing       1  app
  inventory     1  app
  notifications 1  app
  orders        1  app
== contracts
shop layers KEPT
Contracts: 1 kept, 0 broken.
== private access
All checks passed!
== class cohesion (LCOM4)
| shop.app.Shop             | 4    |
| shop.billing.Billing      | 1    |
| shop.billing.Invoice      | 0    |
| shop.inventory.Inventory  | 1    |
| shop.inventory.OutOfStock | 0    |
| shop.notifications.Mailer | 1    |
| shop.orders.Invoicer      | 0    |
| shop.orders.Order         | 0    |
| shop.orders.OrderService  | 1    |
| shop.orders.Stock         | 0    |
| Average                   | 0.80 |
```

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

- الاختبارات الأربعة نفسها نجحت دون تعديل، فالسلوك من الخارج لم يتغير.
- الأسهم نزلت من 14 إلى 4، والدوائر من 3 إلى صفر، وكل الأسهم تخرج من `app` بقيمة 1.00 إلى وحدات قيمتها 0.00، أي أن كل اعتماد ينزل نحو الاستقرار.
- أثر تعديل أي وحدة صار وحدة واحدة هي `app`، بعد أن كان ثلاثاً أو أربعاً أو كل المتجر.
- قاعدة import-linter صارت محفوظة KEPT، وRuff لم يجد أي وصول إلى اسم خاص.
- ولاحظ أن الطلبات صارت قيمتها Ce تساوي صفراً، فهي لا تستورد أي وحدة من المتجر، لأنها تعرف البروتوكولات فقط، ومع ذلك فهي التي تنسق كل العمل.

والصورتان التاليتان تبينان رسم الاعتماديات قبل وبعد، كما حسبناه من مخرج pydeps:

![رسم الاعتماديات قبل التقسيم: ست وحدات و14 سهماً، والأسهم الحمراء تشكل ثلاث دوائر بين orders وbilling وnotifications، وكل الوحدات تشير إلى utils في الأسفل، وسهم متقطع من orders إلى داخل inventory مكتوب عليه _stock](https://arabroot.io/content/images/2026/11/coupling-cohesion-03-graph-before.webp)

قبل التقسيم: 14 سهماً، وثلاث دوائر، وكل شيء يعتمد على utils

![رسم الاعتماديات بعد التقسيم: app في الأعلى وأربعة أسهم خضراء منها إلى orders وbilling وinventory وnotifications، وorders تتصل بالباقي عبر بروتوكولات مرسومة بخط متقطع وليست استيرادات](https://arabroot.io/content/images/2026/11/coupling-cohesion-04-graph-after.webp)

بعد التقسيم: 4 أسهم كلها من جذر التركيب، ولا توجد دوائر

### مفاجأة في الأرقام: LCOM ساء في الواجهة

عندما قارنا مخرج lcom قبل وبعد وجدنا شيئاً لم نتوقعه: الكلاس `Shop` كانت قيمته 1 قبل التقسيم، أي متماسك تماماً، وصارت 4 بعده، أي أسوأ. والسبب في الحالتين يستحق الفهم. فقبل التقسيم كانت دوال `Shop` لا تستخدم حقول الكلاس أصلاً، وإنما تستدعي وحدات أخرى تحمل بياناتها في متغيرات عامة، فلم يجد lcom ما يفصل بينها، والقيمة 1 هنا كانت تخفي الاقتران المشترك الذي رأيناه في تجربة المتجرين، لأن LCOM لا يرى إلا حقول `self`. وبعد التقسيم صار `Shop` يملك أربعة كائنات، وكل دالة فيه تستخدم واحداً منها، فالمخزون لدالتين، والفواتير لدالة، والبريد لدالة، والطلبات لدالة، فخرجت أربع مجموعات.

وهذا ليس خطأ في التصميم، فـ `Shop` واجهة Facade وجذر تركيب، ووظيفته أن يجمع وحدات مستقلة خلف باب واحد، فمن الطبيعي أن تكون دواله منفصلة. والدرس أن المقياس يجيب عن سؤال محدد، وهو هل دوال الكلاس تتشارك حقوله، ولا يجيب عن سؤال هل التصميم جيد، لذلك لا تضع حداً لـ LCOM في خط CI على كل الكلاسات دون استثناء، وراجع كل قيمة عالية بعين بشرية. والأداة cohesion قالت الشيء نفسه بطريقتها، فأعطت `Shop` قبل التقسيم 33.33%، لأن المنشئ ودالة الطلب فقط يستخدمان الحقل الوحيد.

### المتجران بعد التقسيم

وعند تشغيل سيناريو المتجرين نفسه بعد التقسيم:

```text
stock in a: 4 | stock in b: 1
invoices in a: 1 | invoices in b: 0
```

كل متجر يملك مخزونه وفواتيره، فبقي في الأول أربع قطع بعد الطلب، وفي الثاني قطعة، ولم تظهر فاتورة الأول في الثاني. ولم نكتب أي كود خاص لهذا، وإنما جاء من أن البيانات صارت داخل الكائنات بدلاً من الملفات.

### ماذا تقول الأرقام عن مشروع حقيقي؟ مكتبة requests

المتجر مثال كتبناه بأيدينا، فلنقس بالسكربت نفسه مكتبة يستخدمها الملايين، وهي [requests بالإصدار 2.32.5](https://pypi.org/project/requests/2.32.5/?ref=arabroot.io)، بعد تثبيتها من PyPI داخل الـ Container نفسه:

```bash
#!/bin/sh
# Same coupling numbers on an open-source package: requests 2.32.5 installed from PyPI.
pip install -q --no-cache-dir requests==2.32.5
cd /usr/local/lib/python3.13/site-packages
pydeps requests --show-deps --no-output 2>/dev/null | ROOT=requests python /lab/coupling.py
```

```text
module                      Ce  Ca      I   imports
requests.__version__         0   2   0.00   -
requests._internal_utils     1   5   0.17   compat
requests.adapters            7   1   0.88   auth, compat, cookies, exceptions, models, structures, utils
requests.api                 1   0   1.00   sessions
requests.auth                4   3   0.57   _internal_utils, compat, cookies, utils
requests.certs               0   1   0.00   -
requests.compat              0  10   0.00   -
requests.cookies             2   5   0.29   _internal_utils, compat
requests.exceptions          1   4   0.20   compat
requests.help                1   0   1.00   __version__
requests.hooks               0   2   0.00   -
requests.models              9   2   0.82   _internal_utils, auth, compat, cookies, exceptions, hooks, status_codes, structures, utils
requests.packages            1   0   1.00   compat
requests.sessions           11   1   0.92   _internal_utils, adapters, auth, compat, cookies, exceptions, hooks, models, status_codes, structures, utils
requests.status_codes        1   2   0.33   structures
requests.structures          1   5   0.17   compat
requests.utils               7   4   0.64   __version__, _internal_utils, certs, compat, cookies, exceptions, structures
edges: 47
cycles: 0
impact of a change (modules that import it directly or indirectly):
  __version__       7  adapters, api, auth, help, models, sessions, utils
  _internal_utils   7  adapters, api, auth, cookies, models, sessions, utils
  adapters          2  api, sessions
  api               0  -
  auth              4  adapters, api, models, sessions
  certs             6  adapters, api, auth, models, sessions, utils
  compat            12  _internal_utils, adapters, api, auth, cookies, exceptions, models, packages, sessions, status_codes, structures, utils
  cookies           6  adapters, api, auth, models, sessions, utils
  exceptions        6  adapters, api, auth, models, sessions, utils
  help              0  -
  hooks             4  adapters, api, models, sessions
  models            3  adapters, api, sessions
  packages          0  -
  sessions          1  api
  status_codes      4  adapters, api, models, sessions
  structures        7  adapters, api, auth, models, sessions, status_codes, utils
  utils             5  adapters, api, auth, models, sessions
```

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

- في المكتبة 17 وحدة و47 سهماً، ولا توجد دائرة واحدة بين وحداتها، أي أن فريقها حافظ على مبدأ الاعتماديات بلا دوائر في مشروع عمره أكثر من عشر سنوات.
- الوحدة `compat` تعتمد عليها 10 وحدات ولا تعتمد على شيء، فقيمتها 0.00، وأثر تعديلها يصل إلى 12 وحدة. وهي وحدة صغيرة تجمع الفروق بين نسخ Python وأسماء المكتبات البديلة، وتتغير نادراً، لذلك فاستقرارها مقبول. ويسمي Martin الوحدة المستقرة والملموسة غير المجردة «منطقة الألم» Zone of Pain، لأن تغييرها مؤلم، والمخرج هنا أن تبقى صغيرة جداً ونادرة التغيير.
- `sessions` قيمتها 0.92 وتعتمد على 11 وحدة، ولا يعتمد عليها إلا `api`، وهذا هو الاتجاه الصحيح: الوحدة التي تجمع كل شيء غير مستقرة، فيمكن تعديلها دون أن يتأثر إلا القليل.
- `utils` تعتمد على 7 وحدات وتعتمد عليها 4، وقيمتها 0.64، وهي ملف كبير يجمع دوال مساعدة كثيرة. والاسم وحده يخبرك بأن تماسكها أضعف من غيرها، ومع ذلك فإن الأسهم حولها تنزل نحو وحدات أكثر استقراراً، فالمشكلة في حجمها وليس في اتجاه اعتمادها.

والدرس من هذه المقارنة أن الأرقام لا تحكم على التصميم وحدها، فالوحدة ذات القيمة 0.00 قد تكون مقبولة إذا كانت صغيرة ونادرة التغيير مثل `compat`، وقد تكون مشكلة كبيرة إذا كانت كبيرة وتتغير كثيراً مثل `utils` في المتجر. لذلك اجمع رقم الاستقرار مع حجم الوحدة وعدد مرات تعديلها في `git log`، كما شرحنا في فكرة النقاط الساخنة Hotspots في [مقال الدين التقني](https://arabroot.io/articles/%D8%A7%D9%84%D8%AF%D9%8A%D9%86-%D8%A7%D9%84%D8%AA%D9%82%D9%86%D9%8A-technical-debt-%D9%83%D9%8A%D9%81-%D8%AA%D9%82%D9%8A%D8%B3%D9%87-%D9%88%D8%AA%D9%82%D9%86%D8%B9-%D8%A7%D9%84%D8%A7%D8%AF%D8%A7%D8%B1%D8%A9/#hotspots).

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

| المقياس                       | قبل                        | بعد                     | الأداة                 |
| ----------------------------- | -------------------------- | ----------------------- | ---------------------- |
| الاختبارات                    | 4 نجحت                     | 4 نجحت دون تعديل        | pytest                 |
| عدد الوحدات                   | 6                          | 5 (حذف utils)           | pydeps                 |
| الأسهم بين الوحدات            | 14                         | 4                       | pydeps                 |
| الدوائر                       | 3                          | 0                       | pydeps مع سكربت القياس |
| أثر تعديل الفواتير            | 3 وحدات                    | 1                       | pydeps مع سكربت القياس |
| استيرادات تخالف قاعدة الطبقات | 3                          | 0                       | import-linter          |
| وصول إلى أسماء خاصة           | 3                          | 0                       | Ruff SLF001            |
| LCOM4 لكلاس الطلبات           | 4 (OrderManager)           | 1 (OrderService)        | lcom                   |
| LCOM4 للواجهة Shop            | 1                          | 4 (واجهة Facade، مقبول) | lcom                   |
| متجران في برنامج واحد         | يتشاركان المخزون والفواتير | مستقلان                 | سكربت المتجرين         |

![مقارنة بالأعمدة قبل وبعد: الأسهم 14 ثم 4، والدوائر 3 ثم 0، وأثر تعديل الفواتير 3 ثم 1، والاستيرادات المخالفة 3 ثم 0، والوصول إلى الأسماء الخاصة 3 ثم 0، والاختبارات 4 من 4 في المرتين](https://arabroot.io/content/images/2026/11/coupling-cohesion-05-metrics.webp)

كل أرقام الاقتران انخفضت، والاختبارات نفسها بقيت خضراء

### التنظيف Cleanup

```bash
docker rmi sw1-cc:lab
```

## كيف تبدأ في مشروع قائم؟ Baseline ثم تحسين تدريجي

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

1. **اكتب القاعدة كما تريدها، وسجل المخالفات الحالية استثناءات**: import-linter يقبل الخيار `ignore_imports`، فتكتب فيه المخالفات الموجودة اليوم، وتمر القاعدة، وتضعها في خط CI من اليوم الأول.
2. **أي مخالفة جديدة تفشل الخط**: لأن الاستثناءات محددة بالاسم، فإن أي استيراد جديد يخالف القاعدة يوقف الدمج.
3. **احذف سطراً من الاستثناءات مع كل إعادة تقسيم**: كل طلب دمج يمر على وحدة فيها مخالفة فرصة لإصلاحها وحذف سطرها، فتنقص القائمة مع الوقت ولا تزيد.

وهذه القاعدة نفسها للمتجر قبل التقسيم مع الاستثناءات الثلاثة:

```ini
[importlinter]
root_package = shop

[importlinter:contract:layers]
name = shop layers
type = layers
layers =
    shop.app
    shop.orders
    shop.billing | shop.inventory | shop.notifications
# known violations on the day the contract was added; remove one line with each refactor
ignore_imports =
    shop.billing -> shop.orders
    shop.notifications -> shop.billing
    shop.notifications -> shop.orders
```

والسكربت `baseline.sh` يفحص الكود القديم بها، ثم ينسخه ويضيف استيراداً جديداً واحداً في ملف البريد، كما يفعل مطور على عجل، ويفحص مرة أخرى:

```text
shop layers KEPT (3 ignored imports)
Contracts: 1 kept, 0 broken.
shop layers BROKEN (3 ignored imports)
Contracts: 0 kept, 1 broken.
shop.notifications is not allowed to import shop.inventory:
- shop.notifications -> shop.inventory (l.2)
```

القاعدة مرت على الكود القديم مع ذكر الاستيرادات الثلاثة المتجاهلة، ثم فشلت على الاستيراد الجديد وحده، وذكرت الملف والسطر. وبهذا الشكل تحصل على فائدة القاعدة في اليوم الأول دون أن تحتاج إلى إصلاح كل شيء قبل تفعيلها، وهذه الطريقة نفسها تصلح لقواعد Ruff عبر ملف استثناءات، ولأي فحص يدخل على مشروع قديم، كما شرحنا في فكرة الكود الجديد New Code في [مقال جودة الكود](https://arabroot.io/articles/%D9%85%D8%A7-%D9%87%D9%8A-%D8%AC%D9%88%D8%AF%D8%A9-%D8%A7%D9%84%D9%83%D9%88%D8%AF-code-quality-%D9%88%D9%83%D9%8A%D9%81-%D8%AA%D9%82%D9%8A%D8%B3%D9%87%D8%A7/#new-code).

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

## متى يصبح تقليل الاقتران عبئاً؟ Trade-offs

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

- **طبقات من الواجهات لا يطبقها إلا كلاس واحد**: البروتوكولان `Stock` و`Invoicer` في التجربة مبرران، لأن خدمة الطلبات تختبر بهما دون مخزون حقيقي، ولأن كلاً منهما يحتاج دالة واحدة. أما واجهة لكل كلاس لأن «هذا هو التصميم الجيد» فتضاعف عدد الملفات التي يقرؤها من يتتبع طلباً واحداً.
- **الأحداث Events بدلاً من الاستدعاءات داخل البرنامج نفسه**: عندما تستبدل كل استدعاء مباشر بحدث يستمع له أحد ما، يصبح الاقتران مخفياً بدلاً من أن يقل، فلا ترى في الكود من سوف يتأثر، ولا تجده أي أداة استيراد. والاستدعاء المباشر عبر واجهة واضحة أفضل غالباً حتى يظهر سبب حقيقي للفصل الزمني.
- **التقسيم إلى خدمات Microservices لتقليل الاقتران**: إذا كانت الوحدات مقترنة في الكود فإن فصلها إلى خدمات ينقل الاقتران إلى الشبكة، فيصبح أبطأ وأصعب في التتبع، وقد شرحنا هذا القرار في [Monolith أم Microservices](https://arabroot.io/articles/monolith-%D8%A7%D9%85-microservices-%D9%82%D8%B1%D8%A7%D8%B1-%D8%B5%D8%A7%D8%AF%D9%82-%D9%84%D9%84%D9%81%D8%B1%D9%82-%D8%A7%D9%84%D8%B5%D8%BA%D9%8A%D8%B1%D8%A9-%D9%88%D8%A7%D9%84%D9%83%D8%A8%D9%8A%D8%B1%D8%A9/)، والوحدات المستقلة داخل برنامج واحد، كما في التجربة، هي الخطوة الأولى في كل الأحوال، ويسمى هذا الشكل Modular Monolith في [أنماط المعمارية](https://arabroot.io/articles/%D8%A7%D9%86%D9%85%D8%A7%D8%B7-%D8%A7%D9%84%D9%85%D8%B9%D9%85%D8%A7%D8%B1%D9%8A%D8%A9-layered-%D9%88-event-driven-%D9%88-modular-monolith/).

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

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

- **ملف utils أو common أو helpers:** اسم لا يصف مسؤولية، فيصبح الوحدة الأكثر استقراراً والأقل تماسكاً في المشروع، وأي تعديل فيه يمس الجميع. انقل كل دالة إلى الوحدة التي تستخدمها.
- **بيانات على مستوى الملف:** القواميس والقوائم العامة هي اقتران مشترك، وتظهر مشكلتها عندما يوجد كائنان أو اختباران بالتوازي، كما في تجربة المتجرين.
- **الوصول إلى `_private` من خارج الوحدة:** لا تراه أدوات الاستيراد، فأضف قاعدة SLF001 في Ruff أو ما يقابلها في لغتك.
- **قياس الاستيراد فقط:** الدوائر والطبقات تقاس بالاستيراد، ولكن اقتران المحتوى والاقتران المشترك يحتاجان أدوات أخرى ومراجعة بشرية.
- **حد ثابت لـ LCOM على كل الكلاسات:** الواجهات Facades وجذور التركيب تعطي قيماً عالية وهي سليمة، والمتغيرات العامة تعطي قيماً منخفضة وهي سيئة.
- **إعادة التقسيم دون اختبارات على الواجهة العامة:** إذا كانت الاختبارات تستورد `OrderManager` مباشرة فسوف تحتاج إعادة كتابتها، ولن تعرف هل تغير السلوك.
- **الوحدات المستقلة على الورق فقط:** رسم المعمارية يقول إن الفواتير لا تعرف الطلبات، والكود يقول غير ذلك. ضع القاعدة في import-linter داخل خط CI حتى تبقى صحيحة.

## قائمة تحقق Checklist

- كل وحدة تخفي قراراً واحداً يحتمل أن يتغير، ويمكن وصفها بجملة دون «و».
- لا توجد دوائر في رسم الاعتماديات، وأتحقق من ذلك بأداة وليس بالنظر.
- الاعتماد ينزل من الوحدات غير المستقرة إلى المستقرة، والمستقرة مجردة قدر الإمكان.
- الوحدات تتبادل قيماً بسيطة عبر معاملات، ولا تقرأ بيانات بعضها الداخلية.
- لا توجد بيانات قابلة للتعديل على مستوى الملف، والحالة داخل كائنات ينشئها جذر التركيب.
- قواعد الطبقات والاستقلال مكتوبة في import-linter أو ما يقابلها وتعمل في خط CI.
- Ruff بالقاعدة SLF001 أو ما يقابلها يعمل على الكود.
- أراجع القيم العالية لـ LCOM بعين بشرية، وأعرف أن الواجهات تعطي قيماً عالية طبيعية.
- الاختبارات على الواجهة العامة، فتعمل قبل التقسيم وبعده دون تعديل.
- كل اعتماد خارجي جديد له سبب مكتوب ونسخة مثبتة.

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

هذا المقال الثالث في مرحلة معمارية البرمجيات وتصميمها بعد مقال هندسة البرمجيات ومقال البرمجة الكائنية، وما رأيته هنا من بروتوكولات وجذر تركيب هو أساس مبادئ SOLID وأنماط التصميم وClean Architecture.

[![](https://arabroot.io/content/images/2026/11/software-engineering-intro-cover-cover.webp)دليلهندسة البرمجيات Software Engineering: من كود يعمل إلى نظامما الذي يتغير عندما يعيش الكود سنوات ويعدله غيرك، مع تجربة على سكربت تقرير يصبح وحدة مختبرة لها خط CI وأرقام حقيقية للتعقيد والاختبارات.](https://arabroot.io/articles/%D9%85%D8%A7-%D9%87%D9%8A-%D9%87%D9%86%D8%AF%D8%B3%D8%A9-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D9%8A%D8%A7%D8%AA-software-engineering-%D9%85%D9%86-%D9%83%D9%88%D8%AF-%D9%8A%D8%B9%D9%85%D9%84-%D8%A7%D9%84%D9%89-%D9%86%D8%B8%D8%A7%D9%85/)[![](https://arabroot.io/content/images/2026/11/oop-basics-cover-cover.webp)دليلالبرمجة الكائنية OOP للمبتدئين: الوراثة أم التركيب؟الكائنات والواجهات والوراثة وتعدد الأشكال بمثال واحد بلغتي Python وJava، مع أخطاء المترجم الحقيقية وإعادة هيكلة من الوراثة إلى التركيب والاختبارات نفسها تنجح قبل وبعد.](https://arabroot.io/articles/%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D8%A7%D9%84%D9%83%D8%A7%D8%A6%D9%86%D9%8A%D8%A9-oop-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86-%D8%A7%D9%84%D9%88%D8%B1%D8%A7%D8%AB%D8%A9-%D8%A7%D9%85-%D8%A7%D9%84%D8%AA%D8%B1%D9%83%D9%8A%D8%A8/)[![](https://arabroot.io/content/images/2026/10/design-principles-cover-cover.webp)دليلمبادئ التصميم Design Principles بأمثلة قبل وبعدلماذا يعطل تعديل صغير في الفاتورة شيئاً في المحاسبة، وكيف تساعدك مبادئ مثل SOLID وDRY على كود يتغير دون مفاجآت.](https://arabroot.io/articles/%D9%85%D8%A8%D8%A7%D8%AF%D8%A6-%D8%A7%D9%84%D8%AA%D8%B5%D9%85%D9%8A%D9%85-solid-%D9%88-dry-%D9%88-kiss/)[![](https://arabroot.io/content/images/2026/10/clean-architecture-cover-cover.webp)دليلClean Architecture: كيف تعزل منطق العمل عن قاعدة البياناتلماذا تحتاج قاعدة بيانات لكي تختبر قاعدة عمل من سطر واحد، وكيف يعزل اتجاه الاعتماديات منطق العمل عن التفاصيل.](https://arabroot.io/articles/clean-architecture-%D9%88-hexagonal-%D8%A7%D8%AA%D8%AC%D8%A7%D9%87-%D8%A7%D9%84%D8%A7%D8%B9%D8%AA%D9%85%D8%A7%D8%AF%D9%8A%D8%A7%D8%AA/)

## الخلاصة Summary

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

- الاقتران مقدار ما يجب أن تعرفه عن غير الوحدة التي تعدلها، والتماسك مقدار ما يجمع عناصر الوحدة على غرض واحد، والمفهومان من ورقة Stevens وMyers وConstantine سنة 1974.
- أسوأ الاقتران أن تعدل وحدة بيانات أخرى من الداخل، ثم البيانات العامة المشتركة، وأفضله تبادل قيم بسيطة عبر معاملات.
- معيار Parnas للتقسيم هو القرارات التي يحتمل أن تتغير، وليس خطوات المعالجة.
- مقاييس Martin بسيطة: Ca وCe وI = Ce / (Ca + Ce)، ولا دوائر، والاعتماد ينزل نحو الاستقرار.
- في التجربة نزلت الأسهم من 14 إلى 4 والدوائر من 3 إلى صفر والمخالفات من 6 إلى صفر، والاختبارات نفسها نجحت قبل وبعد، والمتجران صارا مستقلين.
- كل أداة ترى جزءاً: الاستيراد لا يرى الوصول إلى الأسماء الخاصة، وLCOM لا يرى المتغيرات العامة ويعطي الواجهات قيماً عالية، لذلك اجمع الأدوات مع المراجعة.

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

- 18 نوفمبر 2026: كتابة المقال، وتنفيذ التجربة على Docker Engine 29.8.0 مع Python 3.13.18 (python:3.13.18-slim) وpytest 9.2.0 وpydeps 3.0.9 وimport-linter 2.16 (grimp 3.20) وlcom 0.1.0 وcohesion 1.2.0 وRuff 0.17.5.