فلسفة تصميم البرمجيات

SKILL.md

---
name: فلسفة تصميم البرمجيات
description: استخدم أثناء كتابة أو تعديل أو مراجعة الكود كلما أضاف التغيير اسمًا مُصدّرًا أو قابلًا للاستيراد، أو أنشأ وحدة، أو فئة، أو مكونًا، أو مساعدًا، أو هوك، أو خدمة، أو غلافًا، أو مركّزًا على الكود المتكرر، أو غيّر واجهة برمجة التطبيقات. قواعد أوسترهاوت (الوحدات العميقة، إخفاء المعلومات، تقليل التعقيد) بالإضافة إلى اختبار الثبات لمشاركة الكود، اختبار تكلفة القارئ، وملاحظة تصميم مطلوبة في النهاية.
---

# فلسفة تصميم البرمجيات (جون أوسترهوت)

## متى تستخدم هذه المهارة

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

## الانحياز الذي يجب تصحيحه

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

## قواعد اتخاذ القرار

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

## الإشارات والاستجابة لكل منها

- ميزة غير مريحة، أو ينتشر تغيير عبر ملفات، أو يجب على المراجع إيجاد اعتماديات مخفية. الاستجابة: ابحث عن إخفاء معلومات مفقودة ووحدات ضحلة. ابحث أيضًا عن خطوات بترتيب ثابت، وعن التعقيد الذي يحمله المستدعون.
- تضيف وحدة، طبقة، خدمة، مساعد، غلاف أو واجهة. أو تضيف نمطًا، خيارًا، رد نداء أو وسيطًا. الاستجابة: أظهر أنها تخفي تعقيدًا أكثر مما تضيف.
- تغير API. الاستجابة: تحقق مما يجب أن يعرفه المستدعي العادي. يجب ألا يحتاج المستدعي إلى ترتيب الاستدعاءات، التمثيل أو التخزين. يجب ألا يحتاج المستدعي إلى النقل، التخزين المؤقت، البروتوكول أو تنسيق الملف. يجب ألا يحتاج المستدعي إلى سير العمل الداخلي أو العديد من خطوات الإعداد.
- تضيف حالة خاصة، علامة، مسار استثناء، شرط أو حاوية يمكن للمستدعين رؤيتها. الاستجابة: اسأل أولاً ماذا يمكن أن تفعل الوحدة المالكة بدلاً من ذلك. يمكنها إزالة الحالة غير الصالحة، عزل السلوك غير المعتاد أو إعطاء عملية أقوى.
- تقسم الكود، تستخرج دالة أو تضيف متغيرًا. الاستجابة: تحقق من أن الحد الجديد أو الاسم يحمل معنى. يجب ألا يضيف فقط قفزات، حالة تمر عبرها، أو خطوات وسيطة يمكن للمستدعين رؤيتها.
- للكود مراحل مثل `prepare`، `process` و `finalize`، أو يجب على المستدعين بناء الكائنات على مراحل. الاستجابة: تحقق من أن ترتيب الوقت هو المفهوم الحقيقي. إذا لم يكن كذلك، نظم الكود حول المسؤوليات المستقرة.
- اسم غامض، يسمي آلية، غير متسق أو يفاجئ القارئ. الاستجابة: فكر مجددًا في حدود التجريد. لا تقبل اسمًا يكاد يكون صحيحًا.
- تعليق طويل، يكرر الكود، يشرح واجهة مربكة، أو يظهر التفاصيل الداخلية لشرح الاستخدام. الاستجابة: غيّر التجريد، أو انقل العقدة المفقودة إلى الواجهة.
- تحسن الأداء. الاستجابة: قِس أولاً، ثم أخفِ التحسين. لا تتخلى عن عمق الوحدة أو إخفاء المعلومات دون دليل على أن المقايضة ضرورية.
- تختبر أو تراجع. الاستجابة: انظر إلى السلوك العام وعقود الواجهة. انظر أيضًا إلى التعقيد المخفي خلف واجهات API المستقرة، والحالات الخاصة المحتفظ بها خلف التجريد.

## قائمة التحقق النهائية

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

## البوابة

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

## اختبار الثبات: شارك فقط الكود الذي يتغير معًا

- استخرج الكود المشترك فقط عندما يحمي قاعدة يمكنك تسميتها. الدليل هو التغيير المشترك: التاريخ يظهر أن النسخ تم إصلاحها أو تغييرها معًا. الكود الذي يبدو مشابهًا فقط ويتغير بشكل مستقل هو قافية. اترك القوافي كنسخ مكررة. ثلاث كتل متشابهة لا تثبت قاعدة.
- يجب أن يزيل الإصلاح المشكلة، لا أن ينقلها. ستة تحويلات تم نقلها إلى مساعد تحويل عام واحد لا تزال ستة تحويلات. اكتب المترجم المطبوع الذي كانت التحويلات تخفيه.
- عندما يكون التجريد خاطئًا، أعد الكود إلى السطر ودع التكرار يعود. لا تثني التجريد باستخدام الأعلام.
- لا تقسم الكود فقط بسبب حجمه. وحدة واحدة بطول 400 سطر تخفي قرارًا واحدًا أفضل من أربع وحدات بطول 100 سطر تتسرب نفس الوصلات.
- القراءة الميكانيكية لـ Clean Code أو SOLID (دوال صغيرة جدًا، فئة واحدة لكل مسؤولية) تعطي وحدات سطحية. هذه المهارة لها أولوية على ذلك الضغط.

## تكلفة القارئ: الاختبار الثالث

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

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

حجم الملف ليس في هذه القائمة عمدًا. الملف الكبير جدًا هو سبب للبحث عن قرار مخفي ثانٍ. ليس سببًا لقطع الملف.

## الأمان

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

## ملاحظة التصميم (مطلوبة عند تطبيق البوابة)

عندما تنطبق البوابة، ضع قسمًا بعنوان `## Design note` في وصف طلب السحب. اكتب من سطرين إلى أربعة:

- كل حد أضفته، والقرار الذي يخفيه.
- كل تكرار احتفظت به عمدًا، والسبب.
- كل جزء سطحي قبلته، والسبب.

إذا لم تنطبق البوابة، اكتب `## Design note` متبوعًا بـ `Gate not applicable: <reason>`. ضع أيضًا ملاحظة التصميم في ملخص خطوتك النهائية.

## وضع المراجعة

استخدم هذا القسم عندما تراجع أو تختبر كودًا كتبه وكيل أو شخص آخر.

1. تحقق من ملاحظة التصميم. عندما تنطبق البوابة ولا يحتوي طلب السحب على قسم `## Design note`، أبلغ عن ملاحظة تعيق التقدم. عندما لا تتفق الملاحظة مع الفرق، أبلغ عن ملاحظة تعيق التقدم.
2. ملاحظة التصميم تعيق التقدم فقط عندما تحقق الشرطين:
   - تسمي قاعدة من هذه المهارة. القاعدة هي قاعدة قرار، البوابة، اختبار الثبات أو عنصر تكلفة القارئ.
   - تذكر تكلفة ملموسة للقارئ أو للتغيير التالي. أمثلة: "يجب أن يعرف المستدعون شكل التخزين." "مفهوم واحد له اسمين." "تغيير الغطاء يحتاج تعديلات في ثلاثة ملفات."
3. علم كل ملاحظة تصميم أخرى على أنها غير معيقة. ضعها في قائمة منفصلة بعنوان "ملاحظات التصميم غير المعوقة". الملاحظة غير المعوقة لا تعيد العمل إلى المنشئ.
4. لا تبلغ عن تفضيل كملاحظة. اسم مختلف، تخطيط ملف أو أسلوب هو تفضيل. يصبح ملاحظة فقط عندما يكسر قاعدة مسماة وله تكلفة ملموسة.
5. عندما تعود نفس ملاحظة التصميم في دورة مراجعة ثانية، قم بتصعيدها. لا تطلب نفس التغيير للمرة الثالثة.

## المهارات ذات الصلة (عند التثبيت)

- `find-shared-code`: بحث تقريري فقط في التاريخ الحديث عن كود يستحق المشاركة. يستخدم اختبار الثبات واختبار العمق لهذه المهارة.
- `refactoring` و `working-effectively-with-legacy-code`: الخطوات الآمنة نحو تصميم أعمق. هذه المهارة تقرر ما إذا كان الحد الجديد يبقى.

## المصدر والترخيص

تبني هذه المهارة على قواعد "القصيرة" لكتاب فلسفة تصميم البرمجيات في مستودع ciembor/agent-rules-books على GitHub (رخصة MIT، الالتزام 893a88a). البوابة، اختبار الثبات، اختبار تكلفة القارئ، ملاحظة التصميم ووضع المراجعة هي إضافات لتلك القواعد. يحتوي المستودع أيضًا على القواعد الكاملة للكتاب.

الوسوم