الفصل 41: كتابة التوثيق
مقدمة
التوثيق الجيد هو الفرق بين كود يفهمه الجميع وكود لا يفهمه أحد.
تعليقات لغة ص
تعليق سطر
sad
# هذا تعليق سطر واحد
متغير س = 42 # تعليق بعد الكودتعليق كتلة
sad
#*
هذا تعليق كتلة
يمتد على عدة أسطر
*#تعليق توثيق
sad
## تحسب مجموع رقمين
## @مدخل أ - الرقم الأول
## @مدخل ب - الرقم الثاني
## @مخرج مجموع الرقمين
دالة جمع(أ، ب)
ارجع أ + ب
نهاية
#**
صنف يمثل طالباً في النظام.
يحفظ اسم الطالب ودرجاته.
@مثال:
متغير ط = جديد طالب("أحمد")
ط.أضف_درجة(95)
**#
صنف طالب
متغير اسم
متغير درجات = []
باني(اسم)
هذا.اسم = اسم
نهاية
## يضيف درجة جديدة للطالب
## @مدخل درجة - رقم من 0 إلى 100
دالة أضف_درجة(درجة)
هذا.درجات = هذا.درجات + [درجة]
نهاية
نهايةأفضل ممارسات التوثيق
| القاعدة | الشرح |
|---|---|
| وثّق لماذا وليس ماذا | الكود يشرح نفسه، وثق السبب |
| كل دالة عامة | يجب أن تكون موثقة |
| أمثلة استخدام | أضف أمثلة في التوثيق |
| حدّث التوثيق | عند تغيير الكود |
التعليقات السيئة
sad
# ✗ سيئ: تعليق واضح من الكود
متغير عداد = عداد + 1 # زيادة العداد بواحد
# ✓ جيد: تعليق يشرح السبب
متغير عداد = عداد + 1 # تخطي العنصر الأول (رأس الجدول)تمرين
وثّق الكود التالي بشكل كامل باستخدام تعليقات التوثيق:
sad
صنف حساب
متغير رصيد
متغير عمليات = []
باني(رصيد_أولي)
هذا.رصيد = رصيد_أولي
نهاية
دالة إيداع(مبلغ)
هذا.رصيد = هذا.رصيد + مبلغ
هذا.عمليات = هذا.عمليات + [{"type": "إيداع"، "amount": مبلغ}]
نهاية
دالة سحب(مبلغ)
إذا (مبلغ > هذا.رصيد)
ارمي "رصيد غير كافي"
نهاية
هذا.رصيد = هذا.رصيد - مبلغ
نهاية
نهاية