تطلب منك المحاسبة تعديلاً صغيراً في الفاتورة: أن يظهر تاريخ الفاتورة بصيغة مختلفة. فتفتح ملف الفواتير، وتعدل سطراً، وتشغل الاختبارات، فيفشل اختبار في ملف البريد الإلكتروني. وعندما تبحث عن السبب تجد أن ملف البريد يقرأ قائمة الفواتير مباشرة ليأخذ منها المبلغ، وأن ملف الطلبات يستدعي الفواتير، والفواتير تقرأ جدول الطلبات وتعدل حالته، وأن هناك ملفاً اسمه utils.py يستورده كل شيء، وفيه حساب الضريبة وإرسال البريد وتاريخ اليوم معاً. وتعديل من سطر واحد صار يحتاج أن تفهم خمسة ملفات، والمراجع يسألك: هل أنت متأكد أن هذا لم يغير شيئاً في المخزون؟ ولا تملك إجابة واثقة.
هذا الشعور له اسمان في هندسة البرمجيات: الاقتران 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، وهدفها أن تجعل تقسيم البرنامج إلى وحدات قراراً له معايير بدلاً من أن يكون ذوقاً شخصياً. وكانت الفكرة الأساسية فيها أن البرنامج الجيد هو الذي تستطيع أن تعدل أو تختبر أو تفهم كل وحدة فيه بأقل قدر من المعرفة عن الوحدات الأخرى، ولقياس ذلك عرفت الورقة مفهومين:
- الاقتران Coupling: قوة العلاقة بين وحدتين، أي كم يجب أن تعرف عن الوحدة الأخرى لكي تفهم هذه أو تعدلها. والهدف اقتران منخفض Low Coupling.
- التماسك Cohesion: قوة العلاقة بين عناصر الوحدة الواحدة، أي هل كل ما في الملف أو الكلاس يخدم غرضاً واحداً. والهدف تماسك عال High Cohesion.
والتشبيه الذي يساعد هنا هو المطبخ: التماسك العالي أن تكون أدوات القهوة كلها في درج واحد، فإذا أردت أن تعد القهوة فتحت درجاً واحداً، والتماسك المنخفض أن يكون في كل درج شيء من كل شيء. والاقتران العالي أن تكون آلة القهوة موصولة بالثلاجة بسلك لا تعرف لماذا، فإذا نقلت الثلاجة توقفت القهوة. والمفهومان مرتبطان، فعندما تجمع ما يتغير معاً في وحدة واحدة يرتفع تماسكها، ويقل في الوقت نفسه اقترانها بغيرها، لأن التغيير صار يحدث داخلها ولا يعبر الحدود. والصورة التالية تبين الحالتين:

درجات الاقتران 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، وهو الأقوى: كل ما في الوحدة يخدم مهمة واحدة يمكن أن تصفها بجملة، مثل «كل ما يخص المال: الضريبة والتقريب والفواتير».
والسؤال العملي الذي يلخص السلمين: إذا أردت أن تصف ما تفعله هذه الوحدة، هل تحتاج كلمة «و»؟ فإذا قلت «تحسب الضريبة وترسل البريد وتعطي تاريخ اليوم» فتماسكها عرضي، وإذا قلت «تحسب الفواتير» فهو وظيفي. والصورة التالية تجمع السلمين:

إخفاء المعلومات 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 سنة 2002، ثم في الجزء الرابع من كتاب Clean Architecture سنة 2017. وثلاثة منها عن الاقتران بين المكونات:
- مبدأ الاعتماديات بلا دوائر Acyclic Dependencies Principle: رسم الاعتماديات بين الوحدات يجب ألا تكون فيه دائرة، لأن الدائرة تعني أن هذه الوحدات لا يمكن فهمها أو اختبارها أو إصدارها إلا معاً، فهي في الحقيقة وحدة واحدة كبيرة.
- مبدأ الاعتماديات المستقرة Stable Dependencies Principle: اعتمد في اتجاه الاستقرار، أي أن الوحدة التي تتغير كثيراً تعتمد على الوحدة التي تتغير قليلاً، وليس العكس.
- مبدأ التجريد المستقر Stable Abstractions Principle: الوحدة المستقرة يجب أن تكون مجردة، أي واجهات أكثر من تفاصيل، حتى يمكن توسيعها دون تعديلها.
ولكي تطبق المبدأ الثاني بالأرقام عرف Martin لكل وحدة رقمين بسيطين: عدد الوحدات التي تعتمد عليها، ويسمى الاقتران الوارد Afferent Coupling واختصاراً Ca، وعدد الوحدات التي تعتمد هي عليها، ويسمى الاقتران الصادر Efferent Coupling واختصاراً Ce، ثم عدم الاستقرار Instability:
I = Ce / (Ca + Ce)والقيمة صفر تعني وحدة مستقرة تماماً: كثيرون يعتمدون عليها وهي لا تعتمد على أحد، فتغييرها صعب ومكلف. والقيمة واحد تعني وحدة غير مستقرة: لا يعتمد عليها أحد وهي تعتمد على غيرها، فتغييرها سهل. والمبدأ يقول إن الأسهم يجب أن تذهب من القيم العالية إلى القيم المنخفضة. وفي Java هناك أداة قديمة مشهورة تحسب هذه الأرقام لكل حزمة اسمها JDepend، أما في Python فسوف نحسبها في التجربة من رسم الاعتماديات الذي تخرجه pydeps، والصورة التالية تبين المبدأ:

وماذا عن تماسك الحزمة؟ Package Cohesion
وضع Martin ثلاثة مبادئ أخرى للتماسك على مستوى الحزمة، أي ماذا تضع معاً في وحدة واحدة:
- مبدأ التكافؤ بين الإصدار وإعادة الاستخدام Reuse/Release Equivalence Principle: ما تعيد استخدامه يجب أن يصدر معاً برقم إصدار واحد، فلا معنى لحزمة نصف دوالها يتبع إصداراً والنصف الآخر يتبع آخر.
- مبدأ الإغلاق المشترك Common Closure Principle: اجمع في الوحدة الواحدة الكلاسات التي تتغير للسبب نفسه وفي الوقت نفسه، وافصل ما يتغير لأسباب مختلفة. وهو مبدأ المسؤولية الواحدة SRP مطبقاً على الحزم، وهو ما جعلنا نضع الضريبة والتقريب والفاتورة في ملف واحد، لأن تغيير نسبة الضريبة يغيرها معاً.
- مبدأ إعادة الاستخدام المشترك Common Reuse Principle: لا تجبر من يستخدم الوحدة على الاعتماد على أشياء لا يحتاجها، فالوحدة التي تستورد
utilsلتأخذ دالة الضريبة صارت تعتمد أيضاً على إرسال البريد وعلى الثابتSMTP_HOST، وأي تغيير فيهما يعني أنها تحتاج اختباراً من جديد.
ويذكر Martin في Clean Architecture أن هذه المبادئ تتجاذب، فالمبدأ الأول والثالث يدفعان إلى وحدات أصغر، والثاني يدفع إلى وحدات أكبر تجمع ما يتغير معاً، وأن المشروع في بدايته يميل إلى الإغلاق المشترك لأن سرعة التطوير أهم، ثم يميل إلى إعادة الاستخدام عندما تكثر الفرق التي تعتمد عليه. أي أن التقسيم الصحيح ليس ثابتاً، وإنما يتغير مع عمر المشروع.
كيف تقيس الاقتران والتماسك بأدوات حقيقية؟
الكلام السابق مفيد في المراجعة، ولكنه يبقى رأياً حتى تقيسه، والأدوات التالية تعطيك أرقاماً من الكود نفسه في Python، ولكل منها ما يراه وما لا يراه:
- pydeps: تقرأ جمل الاستيراد Imports وتبني رسم الاعتماديات بين الوحدات، ويمكن أن تخرجه كصورة مع Graphviz، أو كملف JSON بالخيار
--show-deps، ومنه نحسب Ca وCe وI والدوائر. - import-linter: تكتب فيها قواعد Contracts عن من يحق له أن يستورد من، مثل الطبقات Layers والاستقلال Independence والمنع Forbidden، وتفشل إذا خالف الكود قاعدة، فتصلح لخط CI. وهي مبنية على مكتبة grimp التي تبني رسم الاستيراد.
- lcom: تحسب مقياس نقص التماسك في الدوال Lack of Cohesion of Methods بالصيغة LCOM4، وهو عدد المجموعات المنفصلة من الدوال والحقول داخل الكلاس، فالقيمة 1 تعني كلاساً متماسكاً، و4 تعني أن الكلاس فيه أربعة كلاسات صغيرة لا علاقة بينها. وأصل المقياس من مجموعة مقاييس Chidamber وKemerer في ورقة A Metrics Suite for Object Oriented Design سنة 1994، ثم عدله Hitz وMontazeri إلى الصيغة الرابعة سنة 1995.
- cohesion: تحسب لكل دالة نسبة حقول الكلاس التي تستخدمها، ثم نسبة للكلاس كله، فتعطيك تفصيلاً يبين أي دالة هي الغريبة.
- Ruff بالقاعدة SLF001: تنبه عند الوصول إلى اسم يبدأ بشرطة سفلية من خارج الكلاس أو الوحدة، وهذا هو اقتران المحتوى بالضبط، ولا تراه أي أداة من أدوات الاستيراد لأن الاستيراد نفسه مسموح.
وفي Java وC# هناك أدوات تكتب القواعد كاختبارات، مثل ArchUnit وNetArchTest، وقد استخدمنا فكرتها في مقال Clean Architecture لنمنع منطق العمل من الاعتماد على قاعدة البيانات.
الاقتران الذي لا تراه في الكود: الملفات التي تتغير معاً
كل الأدوات السابقة تقرأ الكود في لحظة واحدة، ولكن هناك نوع من الاقتران لا يظهر في جمل الاستيراد أبداً، وهو الملفات التي تتغير معاً في Git. فإذا كان كل تعديل على ملف الفواتير يصاحبه تعديل على قالب البريد، حتى لو لم يستورد أحدهما الآخر، فبينهما اقتران حقيقي عبر معرفة مشتركة، مثل شكل المبلغ أو أسماء الحقول. ويسمى هذا اقتران التغيير Change Coupling أو الاقتران المنطقي Logical Coupling، وتجده بالنظر إلى الملفات التي تظهر معاً في الـ Commits نفسها عبر git log --name-only، فإذا تكرر الزوج نفسه كثيراً فهذه إشارة إلى أن بينهما قراراً واحداً موزعاً على مكانين، والحل غالباً أن تنقل هذا القرار إلى مكان واحد، أو أن تجعل الملفين في وحدة واحدة. وهذا النوع مهم بشكل خاص عندما تفكر في فصل وحدتين إلى خدمتين، لأن الملفات التي تتغير معاً سوف تعني نشر خدمتين معاً في كل تعديل.
تجربة عملية Lab: قياس متجر صغير ثم إعادة تقسيمه
في هذه التجربة كتبنا متجراً صغيراً بلغة Python بالطريقة التي يكبر بها الكود عادة: ميزة بعد ميزة في أقرب ملف. وفيه خمس وحدات: المخزون، والفواتير، والبريد، والطلبات، وملف المساعدات utils.py، وواجهة عامة واحدة اسمها Shop في app.py يستخدمها كل من يتعامل مع المتجر. ثم قسنا الاقتران والتماسك، وأعدنا تقسيم الكود، وقسنا مرة أخرى. وكل الأوامر تعمل داخل Container، وملفات التجربة كاملة في مجلد lab مع المقال: before وafter والاختبارات وسكربتات القياس.
التجهيز Setup
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 /labdocker 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:
#!/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
ملف المساعدات فيه كل ما لم يجد له أحد مكاناً:
"""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())وملف الفواتير يقرأ جدول الطلبات من ملف الطلبات ويعدل حالة الطلب:
"""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وملف البريد يقرأ الطلبات والفواتير ليكتب الرسالة:
"""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 الذي كبر مع الوقت:
"""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 فهما في مجلد التجربة. وهذا الكود يعمل، والاختبارات الأربعة تنجح، وهي مكتوبة على الواجهة العامة فقط، لذلك سوف نشغلها كما هي بعد التقسيم:
"""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("[email protected]", "KB-1", 2)
assert shop.stock("KB-1") == 3
def test_invoice_includes_vat(shop):
shop.place_order("[email protected]", "KB-1", 2)
assert shop.invoices()[0]["total"] == Decimal("460.00")
def test_customer_gets_one_email_with_the_total(shop):
shop.place_order("[email protected]", "KB-1", 1)
[mail] = shop.sent_emails()
assert mail["to"] == "[email protected]" and "230.00" in mail["body"]
def test_out_of_stock_changes_nothing(shop):
with pytest.raises(OutOfStock):
shop.place_order("[email protected]", "KB-1", 6)
assert shop.stock("KB-1") == 5 and shop.invoices() == [] and shop.sent_emails() == []القياس قبل التقسيم
هذا مخرج measure.sh before:
== 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 التي استخدمناها ملف صغير:
[importlinter]
root_package = shop
[importlinter:contract:layers]
name = shop layers
type = layers
layers =
shop.app
shop.orders
shop.billing | shop.inventory | shop.notificationsوالشرطة العمودية في السطر الأخير تعني أن الوحدات الثلاث في الطبقة نفسها، وأنها مستقلة لا يستورد بعضها بعضاً، كما يشرح توثيق أنواع القواعد. والأداة cohesion تعطي تفصيلاً أدق لكل دالة في OrderManager:
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:
# 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("[email protected]", "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()))والمخرج قبل التقسيم:
stock in a: 0 | stock in b: 0
invoices in a: 1 | invoices in b: 1المتجر الأول أضاف خمس لوحات مفاتيح، والثاني أضاف واحدة، ثم طلب العميل من المتجر الأول قطعة واحدة، فصار المخزون في المتجرين صفراً، وظهرت فاتورة المتجر الأول في المتجر الثاني. والسبب أن كل البيانات في متغيرات على مستوى الملف، وShop في before لا يملك شيئاً، وإنما يمسح هذه المتغيرات عند إنشائه، فالمتجر الثاني مسح طلبات الأول، وأضاف منتجه فوق منتج الأول، وكلاهما يقرأ المخزون نفسه. وهذا هو الاقتران المشترك في أوضح صوره، والاختبارات الأربعة لم تكشفه لأن كل اختبار ينشئ متجراً واحداً، ولو شغلناها بالتوازي لظهرت أخطاء متقطعة يصعب تتبعها.

وقد يتساءل البعض: كيف أكتشف هذا النوع من الاقتران في مشروعي قبل أن يظهر في الإنتاج؟ والإجابة في ثلاث علامات. الأولى أن تبحث عن متغيرات على مستوى الملف تتغير قيمتها، أي قواميس وقوائم تعدل بعد الاستيراد، وليس ثوابت. والثانية أن تجد في الاختبارات دوالاً تمسح حالة عامة قبل كل اختبار، مثل المنشئ Shop() هنا الذي يمسح القوائم العامة، فهذا اعتراف بأن الحالة مشتركة. والثالثة أن تشغل الاختبارات بترتيب عشوائي أو بالتوازي، فالاختبار الذي ينجح وحده ويفشل مع غيره علامة شبه مؤكدة على حالة مشتركة، كما رأينا في تجربة الترتيب العشوائي في مقال اختبارات الوحدة.
إعادة التقسيم Refactoring خطوة خطوة
أعدنا تقسيم المتجر بخمس خطوات، وبعد كل خطوة كانت الاختبارات تعمل:
- إخفاء المخزون: صار المخزون كلاساً يملك بياناته، وأضفنا له دالة
reserveتتحقق من الكمية وتنقصها وترجع سعر السطر، فلم يعد أحد يحتاج_stock. وهذه هي فكرة Parnas: القرار المخفي هو طريقة حفظ الكميات. - فك الدائرة بين الطلبات والفواتير: الفواتير لم تعد تقرأ جدول الطلبات، وإنما تستقبل البيانات التي تحتاجها، أي رقم الطلب والمبلغ الصافي، وترجع الفاتورة، ومن يملك الطلب يغير حالته. وهذا انتقال من اقتران المحتوى إلى اقتران البيانات.
- البريد لا يعرف الطلبات: صار
Mailerيستقبل العنوان والرقم والمبلغ، ولا يستورد أي وحدة من المتجر. - الطلبات تعتمد على واجهات: خدمة الطلبات تعرف بروتوكولين صغيرين
StockوInvoicerودالة للتأكيد، ولا تستورد المخزون ولا الفواتير ولا البريد، وهذا عكس الاعتماديات Dependency Inversion. - حذف utils: الضريبة والتقريب ذهبا إلى الفواتير، والبريد ذهب إلى
Mailer، وتاريخ اليوم صار معاملاً للفواتير، وتحويل النص إلى رابط حذف لأنه لم يكن يستخدمه أحد غير المخزون في دالة لم يستدعها أحد.
ملف الطلبات بعد التقسيم:
"""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")وملف المخزون:
"""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:
"""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)أما الفواتير والبريد فهما في مجلد التجربة، ولا يستورد أي منهما شيئاً من المتجر.
القياس بعد التقسيم
== 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:


مفاجأة في الأرقام: LCOM ساء في الواجهة
عندما قارنا مخرج lcom قبل وبعد وجدنا شيئاً لم نتوقعه: الكلاس Shop كانت قيمته 1 قبل التقسيم، أي متماسك تماماً، وصارت 4 بعده، أي أسوأ. والسبب في الحالتين يستحق الفهم. فقبل التقسيم كانت دوال Shop لا تستخدم حقول الكلاس أصلاً، وإنما تستدعي وحدات أخرى تحمل بياناتها في متغيرات عامة، فلم يجد lcom ما يفصل بينها، والقيمة 1 هنا كانت تخفي الاقتران المشترك الذي رأيناه في تجربة المتجرين، لأن LCOM لا يرى إلا حقول self. وبعد التقسيم صار Shop يملك أربعة كائنات، وكل دالة فيه تستخدم واحداً منها، فالمخزون لدالتين، والفواتير لدالة، والبريد لدالة، والطلبات لدالة، فخرجت أربع مجموعات.
وهذا ليس خطأ في التصميم، فـ Shop واجهة Facade وجذر تركيب، ووظيفته أن يجمع وحدات مستقلة خلف باب واحد، فمن الطبيعي أن تكون دواله منفصلة. والدرس أن المقياس يجيب عن سؤال محدد، وهو هل دوال الكلاس تتشارك حقوله، ولا يجيب عن سؤال هل التصميم جيد، لذلك لا تضع حداً لـ LCOM في خط CI على كل الكلاسات دون استثناء، وراجع كل قيمة عالية بعين بشرية. والأداة cohesion قالت الشيء نفسه بطريقتها، فأعطت Shop قبل التقسيم 33.33%، لأن المنشئ ودالة الطلب فقط يستخدمان الحقل الوحيد.
المتجران بعد التقسيم
وعند تشغيل سيناريو المتجرين نفسه بعد التقسيم:
stock in a: 4 | stock in b: 1
invoices in a: 1 | invoices in b: 0كل متجر يملك مخزونه وفواتيره، فبقي في الأول أربع قطع بعد الطلب، وفي الثاني قطعة، ولم تظهر فاتورة الأول في الثاني. ولم نكتب أي كود خاص لهذا، وإنما جاء من أن البيانات صارت داخل الكائنات بدلاً من الملفات.
ماذا تقول الأرقام عن مشروع حقيقي؟ مكتبة requests
المتجر مثال كتبناه بأيدينا، فلنقس بالسكربت نفسه مكتبة يستخدمها الملايين، وهي requests بالإصدار 2.32.5، بعد تثبيتها من PyPI داخل الـ Container نفسه:
#!/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.pymodule 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 في مقال الدين التقني.
النتائج في جدول 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 |
| متجران في برنامج واحد | يتشاركان المخزون والفواتير | مستقلان | سكربت المتجرين |

التنظيف Cleanup
docker rmi sw1-cc:labكيف تبدأ في مشروع قائم؟ Baseline ثم تحسين تدريجي
المتجر في التجربة صغير، فأعدنا تقسيمه في جلسة واحدة. أما في مشروع حقيقي فيه مئات الملفات فلن تستطيع ذلك، ولن يوافق أحد على إيقاف العمل أسبوعين لإعادة التقسيم. والطريقة العملية أن تمنع الوضع من أن يسوء أولاً، ثم تحسنه مع كل تعديل يمر على المنطقة، وهي ثلاث خطوات:
- اكتب القاعدة كما تريدها، وسجل المخالفات الحالية استثناءات: import-linter يقبل الخيار
ignore_imports، فتكتب فيه المخالفات الموجودة اليوم، وتمر القاعدة، وتضعها في خط CI من اليوم الأول. - أي مخالفة جديدة تفشل الخط: لأن الاستثناءات محددة بالاسم، فإن أي استيراد جديد يخالف القاعدة يوقف الدمج.
- احذف سطراً من الاستثناءات مع كل إعادة تقسيم: كل طلب دمج يمر على وحدة فيها مخالفة فرصة لإصلاحها وحذف سطرها، فتنقص القائمة مع الوقت ولا تزيد.
وهذه القاعدة نفسها للمتجر قبل التقسيم مع الاستثناءات الثلاثة:
[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 يفحص الكود القديم بها، ثم ينسخه ويضيف استيراداً جديداً واحداً في ملف البريد، كما يفعل مطور على عجل، ويفحص مرة أخرى:
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 في مقال جودة الكود.
ومن أين تبدأ الإصلاح؟ ابدأ بالدوائر، لأن كل دائرة تجعل مجموعة وحدات تتصرف كوحدة واحدة، ثم بالوحدة التي أثر تعديلها أكبر وتتغير كثيراً، مثل utils في المتجر، ثم بالوصول إلى البيانات الخاصة، لأنه أخطر أنواع الاقتران وأسهلها إصلاحاً بإضافة دالة واحدة مثل reserve.
متى يصبح تقليل الاقتران عبئاً؟ Trade-offs
الهدف ليس صفر اقتران، فالنظام الذي لا تتكلم وحداته ليس نظاماً، والهدف أن يكون الاقتران قليلاً وواضحاً وفي اتجاه واحد. وهناك ثلاث طرق شائعة للمبالغة:
- طبقات من الواجهات لا يطبقها إلا كلاس واحد: البروتوكولان
StockوInvoicerفي التجربة مبرران، لأن خدمة الطلبات تختبر بهما دون مخزون حقيقي، ولأن كلاً منهما يحتاج دالة واحدة. أما واجهة لكل كلاس لأن «هذا هو التصميم الجيد» فتضاعف عدد الملفات التي يقرؤها من يتتبع طلباً واحداً. - الأحداث Events بدلاً من الاستدعاءات داخل البرنامج نفسه: عندما تستبدل كل استدعاء مباشر بحدث يستمع له أحد ما، يصبح الاقتران مخفياً بدلاً من أن يقل، فلا ترى في الكود من سوف يتأثر، ولا تجده أي أداة استيراد. والاستدعاء المباشر عبر واجهة واضحة أفضل غالباً حتى يظهر سبب حقيقي للفصل الزمني.
- التقسيم إلى خدمات Microservices لتقليل الاقتران: إذا كانت الوحدات مقترنة في الكود فإن فصلها إلى خدمات ينقل الاقتران إلى الشبكة، فيصبح أبطأ وأصعب في التتبع، وقد شرحنا هذا القرار في Monolith أم Microservices، والوحدات المستقلة داخل برنامج واحد، كما في التجربة، هي الخطوة الأولى في كل الأحوال، ويسمى هذا الشكل 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.
دليلهندسة البرمجيات Software Engineering: من كود يعمل إلى نظامما الذي يتغير عندما يعيش الكود سنوات ويعدله غيرك، مع تجربة على سكربت تقرير يصبح وحدة مختبرة لها خط CI وأرقام حقيقية للتعقيد والاختبارات.
دليلالبرمجة الكائنية OOP للمبتدئين: الوراثة أم التركيب؟الكائنات والواجهات والوراثة وتعدد الأشكال بمثال واحد بلغتي Python وJava، مع أخطاء المترجم الحقيقية وإعادة هيكلة من الوراثة إلى التركيب والاختبارات نفسها تنجح قبل وبعد.
دليلمبادئ التصميم Design Principles بأمثلة قبل وبعدلماذا يعطل تعديل صغير في الفاتورة شيئاً في المحاسبة، وكيف تساعدك مبادئ مثل SOLID وDRY على كود يتغير دون مفاجآت.
دليلClean Architecture: كيف تعزل منطق العمل عن قاعدة البياناتلماذا تحتاج قاعدة بيانات لكي تختبر قاعدة عمل من سطر واحد، وكيف يعزل اتجاه الاعتماديات منطق العمل عن التفاصيل.الخلاصة 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.