←
التعليقات

1.7 التعليقات

أهداف التعلم

بنهاية هذا القسم، ينبغي أن تكون قادرًا على:

  • كتابة تعليقات موجزة وواضحة تشرح الغرض من الشِفرة.
  • كتابة سلسلة التوثيق (docstring) (تعليق أكثر تفصيلاً) تصف وظائف البرنامج.

رمز الهاش (#)

التعليقات (Comments) هي عبارات قصيرة تشرح ما تفعله الشِفرة. مثال: تحتوي الأسطر 1 و 8 و 10 في البرنامج التالي على تعليقات. يبدأ كل تعليق برمز الهاش (#). يُتجاهَل كل النص الواقع بين رمز الهاش ونهاية السطر عند تشغيل البرنامج. على النقيض، تُعامَل رموز الهاش داخل السلاسل النصية كنص عادي. مثال: السلسلة النصية "Item #1: " لا تحتوي على تعليق.

عند كتابة التعليقات:

  • يجب أن يتبع رمز # مسافة واحدة. مثال: # End of menu أسهل في القراءة من #End of menu.
  • يجب أن تشرح التعليقات الغرض من الشِفرة، لا أن تكرر الشِفرة نفسها فحسب. مثال: # Get the user's preferences أكثر وصفًا من # Input item1 and item2.

مثال 1.2

برنامج بثلاثة تعليقات

1
# Display the menu options
2
print("Lunch Menu")
3
print("----------")
4
print("Burrito")
5
print("Enchilada")
6
print("Taco")
7
print("Salad")
8
print() # End of menu
9
10
# Get the user's preferences
11
item1 = input("Item #1: ")
12
item2 = input("Item #2: ")

مفاهيم تطبيقية

تعليقات بسيطة

1.
الغرض الرئيسي من كتابة التعليقات هو _____.
  1. تجنب كتابة أخطاء الصياغة
  2. شرح ما تفعله الشِفرة
  3. جعل الشِفرة تعمل بشكل أسرع
2.
ما الرمز المستخدم للتعليقات في بايثون؟
  1. #
  2. /*
  3. //
3.
أي تعليق منسق بشكل صحيح؟
  1. 0 مسافات:
    #Get the user input
  2. 1 مسافة:
    # Get the user input
  3. 2 مسافات:
    #  Get the user input

جودة الشِفرة

كان للبرنامج المثال أعلاه جزآن: (1) عرض خيارات القائمة، و (2) الحصول على تفضيلات المستخدم. معًا، تُظهر الأسطر الفارغة والتعليقات الهيكل العام للبرنامج.

يقضي المبرمجون وقتًا أطول في قراءة الشِفرة منه في كتابتها. لذلك، فمن المهم أن تكون الشِفرة سهلة القراءة والفهم على الآخرين. من طرق تحسين جودة الشِفرة:

  • فصل كل جزء (الأسطر التي لها غرض مماثل) بسطر فارغ.
  • كتابة تعليق قبل كل جزء. ليس كل سطر يحتاج إلى تعليق.

نقطة تحقق

التعليقات في برنامج

مفاهيم تطبيقية

جودة الشِفرة

4.
أي تعليق هو الأكثر فائدة للشِفرة التالية؟ 
print("You said:", adj1 + " " + noun1)
  1. # Append adj1 and noun1
  2. # Print out a bunch of stuff
  3. # Show the resulting phrase
5.
أين يجب إدراج سطر فارغ؟
1
name = input("Whose birthday is today? ")
2
print("Happy birthday to", name)
3
print("Everyone cheer for", name)
  1. بعد السطر 1
  2. بعد السطر 2
  3. بعد السطر 3
6.
لمنع سطر مؤقتًا من التشغيل، يمكنك أن . . .
  1. إدخال خطأ صياغي في السطر.
  2. إزالة السطر من البرنامج.
  3. إدراج # في بداية السطر.

التوثيق

قد تبدأ برامج بايثون اختياريًا بسلسلة نصية تُعرف باسم سلسلة التوثيق (docstring). سلسلة التوثيق هي توثيق يُكتب لمن سيستخدم البرنامج دون أن يقرأ بالضرورة شِفرته المصدرية. يتم إنشاء معظم التوثيق الرسمي على docs.python.org من سلاسل التوثيق.

يمكن أن يكون التوثيق طويلاً، لذا تُكتب سلاسل التوثيق عادةً كسلاسل نصية متعددة الأسطر ((""")). تشمل العناصر الشائعة لسلسلة التوثيق ملخصًا من سطر واحد، وسطرًا فارغًا، ووصفًا أطول.

نقطة تحقق

سلسلة توثيق الإجازات

مفاهيم تطبيقية

التوثيق

7.
الغرض الرئيسي من كتابة سلاسل التوثيق هو . . .
  1. تلخيص غرض البرنامج أو استخدامه.
  2. شرح كيفية عمل كل جزء من الشِفرة.
  3. الاحتفاظ بقائمة من الأفكار للميزات الجديدة.
8.
أي مما يلي ليس سلسلة توثيق؟
  1. """Vacations Madlib."""
  2. """Vacations Madlib.
This program asks the user for two adjectives
and two nouns, which are then used to print
a funny story about a vacation.
"""
  3. # Vacations Madlib.
#
# This program asks the user for two adjectives
# and two nouns, which are then used to print
# a funny story about a vacation.
9.
أي سلسلة توثيق هي الأكثر فائدة لهذا البرنامج؟
  1. """Vacations Madlib."""
  2. """Vacations Madlib. 

This program asks the user for two adjectives
and two nouns, which are then used to print
a funny story about a vacation.
"""
  3. """Vacations Madlib.

This program asks the user for two adjectives
and two nouns, which are then used to print
a funny story about a vacation. The code uses
four variables to store the user input: two for
the adjectives, and two for the nouns. The
output is displayed on seven lines, beginning
with a blank line after the input.
"""

جرّب بنفسك

عيد ميلاد من

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

  • هل تعليقاتك أطول أم أقصر؟ ولماذا؟
  • هل تنسيق تعليقاتك صحيح؟

جرّب بنفسك

حساب الجاذبية

اكتب سلسلة توثيق للبرنامج التالي. يجب أن يشرح السطر الأول من سلسلة التوثيق، في جملة قصيرة واحدة، ما يفعله البرنامج. يجب أن يكون السطر الثاني من سلسلة التوثيق فارغًا. يجب أن تتضمن الأسطر الثالثة وما يليها شرحًا أطول لما يفعله البرنامج. في نهاية سلسلة التوثيق، أضف سطرًا يقول "Author: " متبوعًا باسمك.