مقدمة إلى التعليقات وقابلية قراءة الشيفرة

تُستخدم التعليقات لشرح الكود وجعله أسهل قراءة. ويتجاهلها مفسر Python ولا تؤثر في تنفيذ البرنامج.

في هذا الدرس، ستتعلم كيفية استخدام التعليقات وكتابة كود واضح وسهل القراءة.

التعليقات في سطر واحد

تبدأ التعليقات في سطر واحد بالرمز #. ويتجاهل Python كل ما يأتي بعد الرمز # في ذلك السطر. على سبيل المثال:

# This is a single-line comment
print("Hello, World!")

التعليقات متعددة الأسطر

يمكن كتابة التعليقات متعددة الأسطر باستخدام علامات الاقتباس الثلاثية (''' أو """). على سبيل المثال:

"""
This is a multi-line comment.
It spans multiple lines.
"""
print("Hello, World!")

لماذا نستخدم التعليقات؟

تساعد التعليقات في:

• شرح الكود المعقد.
• جعل الكود أسهل فهمًا للآخرين ولك مستقبلًا.
• تصحيح الأخطاء واستكشاف المشكلات وإصلاحها.

تذكر أن التعليقات مخصصة للبشر، لا للآلة!

ممارسات التعليق الجيدة

إليك بعض النصائح لكتابة تعليقات جيدة:

• اجعل التعليقات موجزة وذات معنى.
• تجنب التعليقات البديهية مثل # Increment x by 1 للكود x = x + 1.
• استخدم التعليقات لشرح سبب كتابة الكود بطريقة معينة.

تحسين قابلية قراءة الشيفرة

يسهل الحفاظ على الكود المقروء وتصحيح أخطائه. إليك بعض النصائح:

• استخدم أسماء واضحة وذات معنى للمتغيرات والدوال.
• اجعل أسطر الكود قصيرة.
• نظّم الكود في أقسام باستخدام التعليقات.

تعطيل الكود باستخدام التعليقات

يمكنك استخدام التعليقات لتعطيل الكود مؤقتًا لأغراض تصحيح الأخطاء. على سبيل المثال:

# print("This line is commented out and won’t run.")
print("This line will run.")

مثال: توثيق دالة

يمكنك استخدام التعليقات لتوثيق الدوال وشرح الغرض منها:

def greet(name):
    # This function greets the user by their name.
    print("Hello,", name)

greet("Alice")

ما الذي تعلمناه؟

في هذا الدرس، تعلمت:

• كيفية كتابة التعليقات في سطر واحد والتعليقات متعددة الأسطر في Python.
• أهمية التعليقات في قابلية قراءة الشيفرة وسهولة صيانتها.
• أفضل الممارسات لكتابة التعليقات وتحسين قابلية قراءة الشيفرة.

أحسنت! لننتقل إلى الموضوع التالي.