التعليقات في بايثون Comments هي ملاحظات داخل ملف الكود لا تنفذها بايثون. لكتابة تعليق عادي استخدم علامة #؛ يبدأ التعليق من هذه العلامة ويستمر حتى نهاية السطر. ويمكن أن يكون التعليق في سطر مستقل أو بعد تعليمة برمجية.
استخدم التعليقات لشرح سبب قرار في الكود أو ملاحظة لا تظهر من القراءة وحدها، وليس لتكرار ما يفعله السطر. وإذا احتجت إلى عدة أسطر من التعليق، ضع # في بداية كل سطر. أما """ ... """ فهي سلسلة نصية وليست صيغة تعليق متعدد الأسطر؛ وقد تصبح Docstring عندما توضع في موضع التوثيق داخل Module أو Function أو Class.
{alertInfo}
الخلاصة السريعة: التعليق الحقيقي في بايثون يبدأ بـ#. استخدمه لشرح السبب أو السياق، وتذكر أن Triple Quotes ليست بديلًا مباشرًا للتعليقات.
{getToc} $title={محتوى المقال}
ما هي التعليقات في بايثون؟
التعليق هو نص يكتبه المبرمج داخل الكود لتوضيح فكرة أو سبب، وتتجاهله قواعد التنفيذ في بايثون. وفق صياغة اللغة الرسمية، يبدأ التعليق بعلامة # عندما لا تكون العلامة داخل String، وينتهي عند نهاية السطر.
# هذا تعليق ولن يتم تنفيذه
print("Hello, Python!")الناتج:
Hello, Python!إذا كنت تتابع الكورس بالترتيب، فالدرس السابق هو شرح Indentation والمسافات البادئة في بايثون. وفهم التعليقات الآن سيساعدك على كتابة الأمثلة القادمة بطريقة أوضح.
كيف تكتب تعليقًا باستخدام #؟
ضع # قبل النص الذي تريد أن تتجاهله بايثون:
# حساب السعر بعد الخصم
price = 100
discount = 20
final_price = price - discount
print(final_price)
لاحظ أن # داخل نص ليست تعليقًا:
print("# هذه العلامة جزء من النص")
السبب أن علامة # هنا موجودة داخل String، ولذلك تبقى جزءًا من القيمة النصية.
كتابة تعليق في نهاية السطر
يمكن وضع تعليق بعد الكود في السطر نفسه. يوصي PEP 8 باستخدام التعليقات الجانبية باعتدال، وترك مسافتين على الأقل قبل # ثم مسافة بعدها.
max_attempts = 3 # منع المحاولات غير المحدودةالتعليق السابق يشرح سبب اختيار القيمة. أما هذا التعليق فليس مفيدًا:
x = x + 1 # أضف 1 إلى xالكود نفسه يقول ذلك بوضوح، لذلك لا يحتاج إلى إعادة شرحه.
كيف تكتب تعليقًا متعدد الأسطر؟
لا توجد في بايثون صيغة مستقلة باسم «تعليق متعدد الأسطر». الطريقة الواضحة هي استخدام # في كل سطر:
# نستخدم هذه الخطوات لأن البيانات الخام
# تحتاج إلى تنظيف قبل حساب النتيجة،
# ثم نعرض القيمة النهائية للمستخدم.
print("Ready")
المحررات الحديثة تستطيع عادة إضافة أو إزالة # من عدة أسطر دفعة واحدة باستخدام اختصار للتعليق، لذلك لا تحتاج إلى كتابة العلامة يدويًا في كل مرة.
هل Triple Quotes تعتبر تعليقًا في بايثون؟
لا. علامات الاقتباس الثلاثية مثل """ ... """ و''' ... ''' تنشئ String Literal متعددة الأسطر. إذا كتبت String منفردة في مكان عادي فقد لا تستخدم نتيجتها، لكنها ما زالت ليست Comment.
"""
هذا نص متعدد الأسطر،
وليس تعليقًا بعلامة #.
"""
print("Program is running")متى تصبح Triple Quotes Docstring؟
إذا كانت السلسلة النصية أول تعليمة داخل Module أو Function أو Class، يمكن أن تستخدم كـDocumentation String أو Docstring:
def greet(name):
"""Return a greeting for the given name."""
return f"Hello {name}"
الـDocstring مخصصة لتوثيق الدالة أو الكلاس أو الموديول، ويمكن للأدوات الوصول إليها. لهذا لا تستخدم Triple Quotes كحيلة لكتابة تعليق عادي عندما يكون # هو المقصود.
| الحالة | الصيغة | الاستخدام |
|---|---|---|
| تعليق عادي | # ملاحظة |
شرح أو ملاحظة تتجاهلها قواعد التنفيذ كتعليق. |
| تعليق عدة أسطر | # في بداية كل سطر |
الطريقة الواضحة لكتابة Block Comment. |
| String متعددة الأسطر | """text""" |
قيمة نصية متعددة الأسطر، وليست تعليقًا. |
| Docstring | """Documentation""" |
توثيق Module أو Function أو Class عندما تأتي في الموضع المناسب. |
استخدام التعليقات لتعطيل كود مؤقتًا
أثناء تجربة الكود أو تضييق نطاق مشكلة، يمكنك تعليق سطر مؤقتًا بدل حذفه:
print("Start")
# print("Temporary test")
print("End")هذا مفيد أثناء التجربة، لكن لا تترك كتلًا كبيرة من الكود المعطل داخل المشروع بلا سبب. إذا لم تعد تحتاج الكود، احذفه بدل تحويل الملف إلى أرشيف لتعليقات قديمة.
كيف تكتب تعليقًا جيدًا؟
أفضل تعليق يضيف معلومة لا يستطيع الكود نفسه إيصالها بسهولة. ركز على لماذا تم اتخاذ القرار، أو على قيد مهم يجب أن يعرفه القارئ.
تعليق ضعيف
total = price * quantity # اضرب السعر في الكميةتعليق أفضل
total = price * quantity # الضريبة تضاف لاحقًا عند إنشاء الفاتورةوفي المقابل، إذا استطعت جعل الكود أو الاسم أوضح بدل إضافة تعليق، فهذا غالبًا أفضل. يمكنك تجربة منسق ومحلل كود بايثون لمراجعة شكل الكود وبعض مؤشرات القراءة.
أخطاء شائعة عند كتابة Comments
| الخطأ | لماذا هو مشكلة؟ | الأفضل |
|---|---|---|
| شرح كل سطر | يزيد الضوضاء ويصعب قراءة الملف. | علّق عندما تضيف سياقًا أو سببًا حقيقيًا. |
| تعليق قديم يخالف الكود | قد يضلل القارئ أكثر من عدم وجود تعليق. | حدّث التعليق مع تحديث الكود. |
| استخدام Triple Quotes كتعليق دائمًا | هي String Literal وقد تكون Docstring في مواضع محددة. | استخدم # للتعليقات العادية. |
| ترك كود معطل بالتعليقات لمدة طويلة | يزيد الفوضى ويصعّب الصيانة. | احذف الكود الذي لم تعد تحتاجه. |
تمرين سريع على التعليقات
جرّب المثال التالي في محرر بايثون العرب، ثم أزل علامة # من السطر المعطل وشغّل الكود مرة أخرى:
# رسالة البداية
print("Welcome to Arab Python")
# print("This line is disabled")
print("Comments lesson completed")أسئلة شائعة
ما رمز التعليق في بايثون؟
رمز التعليق هو #. يبدأ التعليق من هذه العلامة، إذا لم تكن داخل String، ويستمر حتى نهاية السطر.
كيف أكتب Comment على أكثر من سطر؟
استخدم # في بداية كل سطر. لا تعتمد على Triple Quotes باعتبارها صيغة Comments متعددة الأسطر.
هل Triple Quotes تعليق؟
لا. هي String Literal متعددة الأسطر. وقد تُستخدم كـDocstring عندما تأتي في أول موضع مناسب داخل Module أو Function أو Class.
هل يجب أن أكتب تعليقات على كل سطر؟
لا. التعليقات الزائدة تجعل الكود أكثر ضوضاء. اكتبها عندما تضيف سببًا أو سياقًا أو تحذيرًا لا يظهر بوضوح من الكود نفسه.
ما الخطوة التالية في كورس أساسيات بايثون؟
بعد أن فهمت طريقة كتابة التعليقات، انتقل إلى أساسيات بايثون 5: شرح المتغيرات Variables. ويمكنك الرجوع في أي وقت إلى صفحة كورس أساسيات بايثون لمتابعة الدروس بالترتيب.
مصادر رسمية
الخلاصة
التعليقات في بايثون تبدأ بعلامة # خارج النصوص، وتنتهي عند نهاية السطر. استخدمها عندما تحتاج إلى شرح سبب أو سياق مهم، وتجنب التعليقات التي تكرر الكود أو تصبح قديمة بعد التعديل.
أما Triple Quotes فليست تعليقًا متعدد الأسطر؛ هي String Literal، ويمكن أن تؤدي دور Docstring في مواضع التوثيق. عندما تريد تعليقًا عاديًا على عدة أسطر، استخدم # لكل سطر.
{alertSuccess} القاعدة العملية: اكتب كودًا واضحًا أولًا، ثم أضف تعليقًا فقط عندما توجد معلومة مهمة لا يستطيع الكود أن يشرحها وحده.