📐 أفضل الممارسات في لغة ص
الهدف: كتابة كود واضح، قابل للصيانة، وفعّال. هذا الدليل يجمع الممارسات المُختبرة والأنماط الموصى بها.
📖 جدول المحتويات
🏷️ تسمية المتغيرات والدوال
القواعد الذهبية
| ✅ صحيح | ❌ خاطئ | السبب |
|---|---|---|
عدد_الطلاب | ع | الاسم يوضح المحتوى |
احسب_المتوسط | حساب | الفعل يوضح الإجراء |
هل_ناجح | ناجح | البادئة هل_ للمنطقيات |
أقصى_محاولات | ماكس | عربي بالكامل أفضل |
أسماء المتغيرات
sad
# ✅ أسماء واضحة
متغير عدد_الطلاب = 30
متغير سعر_المنتج = 99.99
متغير الاسم_الكامل = "أحمد محمد"
متغير هل_مفعّل = صحيح
# ❌ أسماء غامضة
متغير ع = 30 # ماذا يعني؟
متغير س = 99.99 # غير واضح
متغير ن = "أحمد" # مبهم
متغير ف = صحيح # ما دلالته؟أسماء الدوال
sad
# ✅ أفعال تصف الإجراء
دالة احسب_المتوسط(درجات) ...
دالة أرسل_رسالة(المستلم، النص) ...
دالة تحقق_من_البريد(بريد) ...
# ❌ أسماء غير واضحة
دالة معالجة(بيانات) ... # معالجة ماذا؟
دالة دالة1(س) ... # لا معنى
دالة ف(أ، ب) ... # مبهم تماماًاصطلاحات التسمية
| النوع | الاصطلاح | مثال |
|---|---|---|
| متغير | اسم_بشرطة_سفلية | عدد_الصفحات |
| ثابت | اسم_بشرطة_سفلية (أو أحرف كبيرة للثوابت العالمية) | الحد_الأقصى |
| دالة | فعل_اسم | احسب_الضريبة |
| صنف | اسمبدونشرطة أو اسم_مفرد | طالب, سيارة |
| منطقي | هل_ أو يمكن_ | هل_نشط, يمكن_الحذف |
📏 تنظيم الكود
قاعدة الدالة الواحدة
كل دالة تفعل شيئاً واحداً فقط:
sad
# ✅ دوال مركّزة
دالة احسب_الضريبة(المبلغ)
ارجع المبلغ * 0.15
نهاية
دالة طبّق_الخصم(المبلغ، نسبة_الخصم)
ارجع المبلغ * (1 - نسبة_الخصم / 100)
نهاية
دالة احسب_السعر_النهائي(السعر، الخصم)
متغير بعد_الخصم = طبّق_الخصم(السعر، الخصم)
متغير الضريبة = احسب_الضريبة(بعد_الخصم)
ارجع بعد_الخصم + الضريبة
نهاية
# ❌ دالة تفعل كل شيء
دالة احسب(السعر، الخصم)
متغير بعد_الخصم = السعر * (1 - الخصم / 100)
متغير الضريبة = بعد_الخصم * 0.15
اطبع_سطر("السعر الأصلي: " + السعر)
اطبع_سطر("الخصم: " + الخصم + "%")
اطبع_سطر("الضريبة: " + الضريبة)
اطبع_سطر("الإجمالي: " + (بعد_الخصم + الضريبة))
# خلطت الحساب بالطباعة — صعبة الاختبار والصيانة
نهايةطول الدالة المثالي
┌─────────────────────────────────────────────────────────┐
│ مثالي: 5-15 سطر │
│ مقبول: 15-30 سطر │
│ ⚠️ تحتاج مراجعة: 30-50 سطر │
│ 🔴 يجب تقسيمها: > 50 سطر │
└─────────────────────────────────────────────────────────┘تنظيم الملف
sad
# ═══════════════════════════════════════════════════════
# اسم الملف: إدارة_الطلاب.ص
# الوصف: دوال إدارة بيانات الطلاب
# ═══════════════════════════════════════════════════════
# ─────────────────────────────────────────────────────────
# 1. الاستيرادات
# ─────────────────────────────────────────────────────────
استورد ملفات
استورد json
# ─────────────────────────────────────────────────────────
# 2. الثوابت
# ─────────────────────────────────────────────────────────
ثابت الحد_الأدنى_للنجاح = 60
ثابت أقصى_عدد_طلاب = 100
# ─────────────────────────────────────────────────────────
# 3. الأصناف
# ─────────────────────────────────────────────────────────
صنف طالب
# ...
نهاية
# ─────────────────────────────────────────────────────────
# 4. الدوال المساعدة (خاصة)
# ─────────────────────────────────────────────────────────
دالة _تحقق_من_الدرجة(درجة)
ارجع درجة >= 0 و درجة <= 100
نهاية
# ─────────────────────────────────────────────────────────
# 5. الدوال العامة (API)
# ─────────────────────────────────────────────────────────
دالة أضف_طالب(الاسم، الدرجة)
# ...
نهاية
# ─────────────────────────────────────────────────────────
# 6. نقطة الدخول (إذا كان ملف رئيسي)
# ─────────────────────────────────────────────────────────
# رئيسية()💬 التعليقات الفعّالة
متى تُعلّق؟
| ✅ علّق عندما | ❌ لا تُعلّق عندما |
|---|---|
| تشرح لماذا (القرار) | تشرح ماذا (واضح من الكود) |
| توثّق حالة استثنائية | تكرر ما يقوله الكود |
| تحذّر من خطر | الكود بسيط وواضح |
أمثلة
sad
# ✅ تعليق مفيد — يشرح "لماذا"
# نضرب في 1000 لأن الـ API يتوقع المبلغ بالهللات وليس الريالات
متغير المبلغ_بالهللات = السعر * 1000
# ❌ تعليق غير مفيد — يكرر ما يقوله الكود
# نجمع أ مع ب
متغير المجموع = أ + ب
# ✅ تحذير مهم
# ⚠️ لا تغيّر ترتيب هذه العمليات — يعتمد عليها نظام الدفع
# ⚠️ تم اختبارها مع بنك الرياض فقطتعليقات التوثيق
sad
##
# يحسب مؤشر كتلة الجسم (BMI)
# @معامل الوزن: الوزن بالكيلوجرام
# @معامل الطول: الطول بالمتر
# @يُرجع: مؤشر كتلة الجسم (عشري)
# @مثال: احسب_bmi(70، 1.75) → 22.86
##
دالة احسب_bmi(الوزن، الطول)
ارجع الوزن / (الطول ** 2)
نهاية🛡️ معالجة الأخطاء
تحقق من المدخلات
sad
# ✅ تحقق في بداية الدالة
دالة اقسم(أ، ب)
إذا (ب == 0)
ارمي "لا يمكن القسمة على صفر"
نهاية
ارجع أ / ب
نهاية
# ✅ تحقق من النطاق
دالة حدد_التقدير(درجة)
إذا (درجة < 0 أو درجة > 100)
ارمي "الدرجة يجب أن تكون بين 0 و 100"
نهاية
# ... باقي المنطق
نهايةاستخدم حاول/امسك بحكمة
sad
# ✅ امسك أخطاء محددة وعالجها
حاول
متغير بيانات = اقرأ_ملف("config.json")
متغير إعدادات = حلل_json(بيانات)
امسك خطأ_ملف
اطبع_سطر("⚠️ ملف الإعدادات غير موجود — استخدام القيم الافتراضية")
متغير إعدادات = الإعدادات_الافتراضية()
امسك خطأ_json
اطبع_سطر("⚠️ ملف الإعدادات تالف")
ارمي خطأ_json
نهاية
# ❌ تجنب امسك الفارغ
حاول
# عمليات خطرة
امسك خطأ
# لا شيء — الخطأ يختفي بصمت! 🔴
نهايةأرجع القيم بدلاً من الأخطاء (عند الإمكان)
sad
# ✅ استخدم لاشيء للدلالة على عدم وجود النتيجة
دالة ابحث_عن_طالب(الاسم)
لكل طالب في الطلاب
إذا (طالب.الاسم == الاسم)
ارجع طالب
نهاية
نهاية
ارجع لاشيء # لم يُوجد
نهاية
# عند الاستخدام
متغير نتيجة = ابحث_عن_طالب("أحمد")
إذا (نتيجة == لاشيء)
اطبع_سطر("الطالب غير موجود")
وإلا
اطبع_سطر("وجدنا: " + نتيجة.الاسم)
نهاية🔄 الحلقات والشروط
تجنب التعشيش العميق
sad
# ❌ تعشيش عميق — صعب القراءة
دالة عالج_طلب(الطلب)
إذا (الطلب != لاشيء)
إذا (الطلب.المستخدم != لاشيء)
إذا (الطلب.المستخدم.نشط)
إذا (الطلب.المنتج.متوفر)
# المنطق الفعلي هنا
نهاية
نهاية
نهاية
نهاية
نهاية
# ✅ ارجع مبكراً — أوضح
دالة عالج_طلب(الطلب)
إذا (الطلب == لاشيء)
ارجع "طلب فارغ"
نهاية
إذا (الطلب.المستخدم == لاشيء)
ارجع "مستخدم غير موجود"
نهاية
إذا (ليس الطلب.المستخدم.نشط)
ارجع "المستخدم غير نشط"
نهاية
إذا (ليس الطلب.المنتج.متوفر)
ارجع "المنتج غير متوفر"
نهاية
# المنطق الفعلي — واضح ومباشر
ارجع نفّذ_الطلب(الطلب)
نهايةاستخدم طابق بدلاً من إذا المتعددة
sad
# ❌ سلسلة إذا طويلة
إذا (الحالة == "جديد")
# ...
وإلا إذا (الحالة == "قيد_المعالجة")
# ...
وإلا إذا (الحالة == "مكتمل")
# ...
وإلا إذا (الحالة == "ملغي")
# ...
نهاية
# ✅ طابق أوضح
طابق (الحالة)
عندما "جديد":
# ...
عندما "قيد_المعالجة":
# ...
عندما "مكتمل":
# ...
عندما "ملغي":
# ...
افتراضي:
# حالة غير معروفة
نهايةتفضيل لكل على بينما
sad
# ✅ لكل — أوضح وأأمن
لكل عنصر في القائمة
اطبع_سطر(عنصر)
نهاية
# ⚠️ بينما — استخدمها فقط عند الحاجة للتحكم الكامل
متغير ع = 0
بينما (ع < طول(القائمة))
اطبع_سطر(القائمة[ع])
ع = ع + 1
نهاية🏗️ البرمجة الكائنية
صنف واحد — مسؤولية واحدة
sad
# ❌ صنف يفعل كل شيء
صنف مدير_الطلاب
# يدير الطلاب
# يحسب الدرجات
# يطبع التقارير
# يرسل الإشعارات
# يتصل بقاعدة البيانات
# 😵 كثير جداً!
نهاية
# ✅ أصناف متخصصة
صنف طالب
# بيانات الطالب فقط
نهاية
صنف حاسب_الدرجات
# حسابات الدرجات فقط
نهاية
صنف مولد_التقارير
# التقارير فقط
نهاية
صنف مرسل_الإشعارات
# الإشعارات فقط
نهايةاستخدم الوراثة بحذر
sad
# ✅ وراثة منطقية
صنف شكل
دالة مجرد احسب_المساحة()
نهاية
صنف مستطيل يرث شكل
متغير الطول
متغير العرض
دالة احسب_المساحة()
ارجع هذا.الطول * هذا.العرض
نهاية
نهاية
صنف دائرة يرث شكل
متغير نصف_القطر
دالة احسب_المساحة()
ارجع 3.14159 * هذا.نصف_القطر ** 2
نهاية
نهاية
# ❌ وراثة غير منطقية
صنف سيارة يرث محرك # سيارة ليست نوعاً من المحرك!
# السيارة "تحتوي على" محرك (تركيب)فضّل التركيب على الوراثة
sad
# ✅ التركيب — أكثر مرونة
صنف سيارة
متغير المحرك # سيارة تحتوي على محرك
متغير الإطارات # سيارة تحتوي على إطارات
متغير البطارية # سيارة تحتوي على بطارية
دالة شغّل()
هذا.المحرك.ابدأ()
نهاية
نهاية⚡ الأداء
تجنب العمليات المكررة
sad
# ❌ حساب متكرر داخل الحلقة
لكل ع في 1..1001
إذا (ع < احسب_الحد(البيانات)) # تُحسب 1000 مرة!
# ...
نهاية
نهاية
# ✅ احسب مرة واحدة قبل الحلقة
متغير الحد = احسب_الحد(البيانات)
لكل ع في 1..1001
إذا (ع < الحد)
# ...
نهاية
نهايةاستخدم هياكل البيانات المناسبة
sad
# ❌ البحث في مصفوفة — O(n)
متغير أسماء = ["أحمد"، "سارة"، "محمد"، ...]
إذا ("أحمد" في أسماء) # يفحص كل عنصر
# ...
نهاية
# ✅ البحث في خريطة — O(1)
متغير أسماء = {"أحمد": صحيح، "سارة": صحيح، "محمد": صحيح، ...}
إذا (أسماء["أحمد"]) # فوري
# ...
نهايةتجنب بناء نصوص في حلقة
sad
# ❌ بطيء — يُنشئ نص جديد كل مرة
متغير نتيجة = ""
لكل كلمة في الكلمات
نتيجة = نتيجة + كلمة + " " # O(n²)
نهاية
# ✅ أسرع — استخدم مصفوفة ثم صِل
متغير أجزاء = []
لكل كلمة في الكلمات
أجزاء.أضف(كلمة)
نهاية
متغير نتيجة = صل(أجزاء، " ") # O(n)🧪 قابلية الاختبار
اكتب دوال قابلة للاختبار
sad
# ❌ صعبة الاختبار — تعتمد على الوقت الحالي
دالة هل_يوم_عمل()
متغير اليوم = الآن().يوم_الأسبوع()
ارجع اليوم >= 1 و اليوم <= 5
نهاية
# ✅ سهلة الاختبار — تستقبل اليوم كمعامل
دالة هل_يوم_عمل(اليوم)
ارجع اليوم >= 1 و اليوم <= 5
نهاية
# يمكن اختبارها بسهولة:
# تأكد(هل_يوم_عمل(1) == صحيح)
# تأكد(هل_يوم_عمل(6) == خطأ)افصل المنطق عن الإدخال/الإخراج
sad
# ❌ المنطق مخلوط بالطباعة
دالة احسب_واطبع(درجات)
متغير المجموع = 0
لكل د في درجات
المجموع = المجموع + د
نهاية
اطبع_سطر("المتوسط: " + (المجموع / طول(درجات)))
نهاية
# ✅ فصل المنطق
دالة احسب_المتوسط(درجات)
متغير المجموع = 0
لكل د في درجات
المجموع = المجموع + د
نهاية
ارجع المجموع / طول(درجات)
نهاية
# الطباعة منفصلة
اطبع_سطر("المتوسط: " + احسب_المتوسط(درجات))📋 قائمة التحقق السريعة
قبل تسليم الكود، راجع:
التسمية
- [ ] أسماء المتغيرات واضحة ووصفية
- [ ] أسماء الدوال تبدأ بفعل
- [ ] المنطقيات تبدأ بـ
هل_أويمكن_
التنظيم
- [ ] كل دالة تفعل شيئاً واحداً
- [ ] لا يوجد تعشيش أعمق من 3 مستويات
- [ ] الملف منظم (استيرادات → ثوابت → أصناف → دوال)
الأخطاء
- [ ] المدخلات مُتحقق منها
- [ ] الأخطاء مُعالجة بوضوح
- [ ] لا يوجد
امسكفارغ
التعليقات
- [ ] التعليقات تشرح "لماذا" وليس "ماذا"
- [ ] الدوال العامة موثّقة
- [ ] لا توجد تعليقات قديمة/خاطئة
الأداء
- [ ] لا توجد حسابات مكررة في الحلقات
- [ ] هياكل البيانات مناسبة للعملية
🎯 خلاصة
الكود الجيد يُقرأ كنص عربي واضح.
اتبع هذه المبادئ الثلاثة:
- الوضوح أولاً — الكود يُقرأ أكثر مما يُكتب
- البساطة — أبسط حل صحيح هو الأفضل
- الاتساق — اتبع نمطاً واحداً في كل المشروع
هل لديك اقتراح لممارسة جديدة؟ شاركنا على GitHub!