كيفية التعليق على كتلة من الشفرة في بايثون

Comments are one of the most useful tools when working with Python. They guide us through the logic, decisions, and purposes behind blocks of code without interfering with the execution. Comments help make the code more readable and maintainable and facilitate collaboration in a team setting.

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

لماذا تُعتبر التعليقات البلوكية في Python مهمة؟

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

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

استخدام التعليقات الخطوة الواحدة في بايثون

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

1. الموضع: وضع الرمز # في بداية السطر أو بعد الكود في نفس السطر. يمكن وضع التعليقات فوق الكود التي تصفها، إلى اليمين من الكود في نفس السطر، أو منفصلة.
2. المحتوى: بعد الرمز #، أكتب تعليقك. يمكن أن يكون هذا تفسير سطر الكود، ملاحظة للإشارة للمستقبل أو أي معلومات مفيدة ذات صلة بالكود.

# هذا تعليق خطوة واحدة يشرح السطر التالي من الكود
print("Hello, world!")  # هذا يطبع رسالة إلى الكونسول

طريقة #1: التعليق باستخدام عدة خطوات واحدة #

لأكثر سهولة، يمكنك التعليق في بايثون باستخدام الرمز #، الذي يعطل كل ما يليه في السطر. بينما لا يحتوي بايثون على سيntax محدد للتعليقات البلوكية، يمكنك إستخدام العديد من الرموز # لتعليق كل سطر على حدة. كل ما عليك فعله هو إجراء الخطوات التالية:

1. تحديد البلوك البرمجي: أولاً، تحديد البلوك البرمجي الذي تريد تعليقه. قد يكون هذا وظيفة، دائرة، أو أي قطعة من الكود التي تريد تعطيلها أو توضيحها.
2. تعليق كل سطر: وضع رمز # في بداية كل سطر تريد تعليقه. هذا يخبر معالج بايثون أن يتجاهل هذه السطور أثناء التنفيذ.

يمكنك رؤية العينة أدناه:

# مثال على تعليق عدة سطور بشكل فردي
# def example_function(name):
#	# هذه الوظيفة تطبع "مرحبا " واسم الإدخال
# 	print("مرحبا،", name)

طريقة تعليق البلوك في بايثون الثانية: استخدام التعليمات النصية المتكونة من ثلاثة تقويم.

ar
وسيلة بديلة لتعليق الأسطر المتعددة هي استخدام النصوص المعبرة بثلاثة إقتباسات (”’ ”’ أو “”” “””). وبالرغم من أنها ليست تعليقات البلوك الرسمية، هذه النصوص المعبرة غالبا ما يستخدمت كما تلك، خاصةً للتعليقات المتعددة الأسطر أو سلاسل الوثائق. لاستخدام النصوص المعبرة بثلاثة الإقتباسات، فقط وضع ”’ أو “”” قبل وبعد الكود الذي تريد تعليقه، كما يلي:

'''
def example_function(name):
	print("Hello", name)
'''

النصوص المعبرة بثلاثة الإقتباسات تستخدم الأشد مستوىً لتوثيق وظائف Python. مثلاً:

# إنشاء example_function()
def example_function(name):
	'''
	This function takes as input a name, and returns a salutation to the name in the form of "Hello name"
	'''
	# طباعة الخرج
	print("Hello", name)

هذه النصوص المعبرة بالإقتباسات الثلاثية تُسمى سلاسل الوثائق — يمكنك القراءة المزيد عنها في درس سلاسل الوثائق.