يقضي المطورون وقتًا أطول بكثير في قراءة التعليمات البرمجية مقارنة بكتابتها، مما يجعل قابلية قراءة التعليمات البرمجية جانبًا مهمًا للغاية في إنشاء منتجات برمجية فعالة وقابلة للصيانة. تلعب التعليقات دورًا رئيسيًا في تحسين قابلية قراءة التعليمات البرمجية.
ما هو التعليق؟
التعليق هو جزء من النص يوضع في الكود ويحتوي على معلومات حول ما يفعله الكود. يمكن أن يكون شرحًا للمبرمجين الآخرين الذين يقرؤون الكود أو ملاحظة لاستخدامك لاحقًا. يتم تجاهل التعليقات بواسطة المترجم والمفسر، وبالتالي ليس لها أي تأثير على تنفيذ الكود.
على الرغم من أن بايثون لغة بديهية للغاية ذات بناء جملة سهل الفهم، إلا أن المبرمجين ما زالوا يكتبون تعليقات في بعض أجزاء من أكوادهم. في هذه المقالة، سنتعرف على سبب ضرورة التعليقات بالإضافة إلى كيفية التعليق في بايثون. سنتناول أيضًا بعض الحالات التي لا تكون فيها التعليقات مفيدة ويجب تجنب استخدامها. قبل أن نبدأ مناقشتنا حول كيفية ومتى تكتب التعليقات، دعنا أولاً نتعرف على أنواع التعليقات المختلفة في بايثون.
أنواع التعليقات في بايثون
تعليقات السطر الواحد: بناء الجملة الأساسي لتعليقات بايثون
توجد طرق مختلفة لكتابة التعليقات في بايثون. تعتمد طريقة كتابة التعليق على طول التعليق واختيار المبرمج. لنبدأ أولاً بمثال بسيط يوضح صيغة التعليقات في بايثون:
# Initializing first two Fibonacci Numbers
a, b = 0, 1
تبدأ التعليقات بعلامة التجزئة (#
) وحرف مسافة واحد. في المثال أعلاه، النص بعد علامة التجزئة هو تعليق، والذي يعطي معلومات حول ما يفعله الكود في السطر التالي. هذا مثال لتعليق من سطر واحد.
تعليقات مضمنة
يمكننا أيضًا كتابة تعليقات على نفس سطر العبارة، باتباع التعليمات البرمجية. تُسمى هذه التعليقات بالتعليقات المضمنة، والتي تبدأ أيضًا بعلامة تجزئة ومسافة بيضاء واحدة:
learning_rate = 0.02 # Initialize the learning rate
تعليقات متعددة الأسطر
في بعض الحالات، لا يتناسب التعليق مع سطر واحد؛ بل يمتد إلى عدة أسطر. وتسمى هذه التعليقات بالتعليقات متعددة الأسطر. ويمكننا كتابة التعليقات متعددة الأسطر بطريقتين مختلفتين.
الطريقة الأولى هي استخدام سلاسل نصية متعددة الأسطر. يتجاهل المترجم السلاسل النصية متعددة الأسطر التي لم يتم تعيينها لمتغير، وبالتالي يمكن استخدامها كتعليقات. فيما يلي مثال:
"""
Regex to check if the input is a valid email address
1. Checks email starts with a set of alphanumeric characters.
2. This is followed by the @ symbol.
3. Another set of alphanumeric characters follow (1 or more)
"""
pattern = r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,3}\b'
الطريقة الأخرى هي التعليقات التي تمتد إلى عدة أسطر حيث يبدأ كل سطر بعلامة تصنيف. دعنا نعيد كتابة المثال أعلاه بهذه الطريقة:
# Regex to check if the input is a valid email address
# 1. Checks email starts with a set of alphanumeric characters.
# 2. This is followed by the @ symbol.
# 3. Another set of alphanumeric characters follow (1 or more)
pattern = r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,3}\b'
في هذا المثال، سيؤدي كتابة محتوى التعليق بالكامل في سطر واحد إلى سطر طويل للغاية، مما يصعب قراءته. إن استخدام تعليق متعدد الأسطر يجعل قراءته أسرع كثيرًا. كما أننا قادرون على تنفيذ بنية متسلسلة، مما يجعل التعليق أسهل على الآخرين فهمه.
متى تستخدم التعليقات
لقد تعلمنا طرقًا مختلفة لكتابة التعليقات في بايثون. الآن دعنا نناقش متى يكون من المناسب إضافة التعليقات إلى نصوصنا البرمجية. سنتناول عدة حالات حيث يعمل التعليق كأصل مفيد في كتابة كود نظيف.
تعليقات إعلامية
تُستخدم التعليقات المعلوماتية لشرح ما يفعله جزء معقد من التعليمات البرمجية. يفكر المبرمجون في كتابة التعليقات حيث يعتقدون أنه قد يكون من الصعب على الآخرين فهم التعليمات البرمجية. إحدى حالات الاستخدام النموذجية هي كتابة تعليق يشرح ما يتطابق مع تعبير عادي (أي تعبير عادي)، والذي قد يكون معقدًا حقًا ويتطلب من الآخرين إجراء بعض الأبحاث لفهمه.
# Regex to match an email address (example: john.doe@example.com)
email_pattern = r"(^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$)"
إذا لم تكن على دراية بالتعبيرات العادية، فستحتاج إلى قضاء قدر كبير من الوقت لفهم ما يتطابق مع نمط التعبيرات العادية في هذا المثال. بالإضافة إلى ذلك، ما لم يكن الكود مكتوبًا لتعليم شخص ما أنماط التعبيرات العادية، فما الهدف من جعله يحاول جاهدًا فهمه؟ يمكنه فقط قراءة التعليق والمتابعة ببقية النص. هذا مثال رائع يوضح مدى فائدة التعليق ووظيفته.
التعليقات القانونية
هناك حالات حيث تكون التعليقات ضرورية لأسباب قانونية (على سبيل المثال لتوفير معلومات حقوق الطبع والنشر). فيما يلي مثال حيث يتم استخدام التعليقات لتحديد معلومات حقوق الطبع والنشر.
# Copyright (c) 2023, Your Name or Company
# All rights reserved.
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the code retains the
# above copyright notice.
توضيح القصد
في بعض الحالات، من المفيد جدًا شرح الغرض حتى يتمكن المطورون الآخرون من فهم سبب اختيارك لكتابة جزء من التعليمات البرمجية بالطريقة التي قمت بها. فيما يلي مثال بسيط مع تعليق للإشارة إلى استخدام فهم القائمة بدلاً من حلقة for:
# Using list comprehension instead of a for-loop for performance reasons
squared_values = [x**2 for x in range(1000)]
التعليق على الكود من أجل تصحيح الأخطاء
ذكرنا أن التعليقات يتم تجاهلها بواسطة المترجم. لذا عندما نقوم بتصحيح أخطاء نص برمجي أو البحث عن عنق زجاجة يتسبب في حدوث مشكلات في الأداء، يمكننا التعليق على جزء من الكود وتشغيل بقية الكود. إذا تم إصلاح الخطأ أو مشكلة الأداء بعد التعليق على جزء معين من النص البرمجي، فيمكننا افتراض أن الجزء الذي تم التعليق عليه يمثل مشكلة – أو على الأقل إجراء مزيد من البحث في الجزء الذي تم التعليق عليه للعثور على المشكلة بالضبط.
في المثال التالي، يتم التعليق على تنفيذ دالة generate_tax. إذا تم حل مشكلة بعد التعليق على هذا السطر، فيمكننا التحقق من كود هذه الدالة لحل المشكلة:
# calculated_tax = generate_tax(income, tax_rate)
تعليقات سيئة
لا ينبغي لنا استخدام التعليقات لشرح الكود المكتوب بشكل سيئ. من الأفضل عدم استخدام التعليقات إلا إذا كان ذلك ضروريًا. إذا شعرت أن الكود الخاص بك يحتاج إلى تعليقات، فحاول إعادة كتابته بحيث يكون واضحًا ويصبح استخدام التعليقات غير ضروري.
في المثال التالي، اسم الدالة واضح جدًا وما تفعله واضح جدًا. وبالتالي، فإن التعليق الموجود أعلى اسم الدالة غير ضروري.
import math
# Calculates the area of a circle
def calculate_circle_area(radius):
return math.pi * radius * radius
ذكرنا سابقًا أننا نعلق أحيانًا على جزء من الكود بغرض تصحيح الأخطاء. وبعد اكتمال هذه العملية، قد ينتهي بنا الأمر إلى الحصول على كود لم يعد هناك حاجة إليه. وفي مثل هذه الحالات، لا ينبغي لنا تركه ككود معلق عليه. بل يجب علينا بدلاً من ذلك حذف هذا الجزء من الكود والحفاظ على النص نظيفًا وسهل القراءة. ونظرًا لأن جميع قواعد الكود تقريبًا تُدار بنظام التحكم في الإصدار (مثل Git)، فيمكننا دائمًا الرجوع إلى إصدار آخر إذا احتجنا مرة أخرى إلى جزء من الكود معلق عليه.
من المهم جدًا تحديث التعليقات باستمرار مع تطور الكود، وإلا فإنها ستسبب ضررًا أكثر من نفعها وستكون مضللة.
في المثال التالي، يتم استخدام تعليق للإشارة إلى معدل الضريبة. ومع ذلك، فإن معدل الضريبة المُعلَّق عليه يختلف عن المعدل المستخدم في الكود الفعلي. وبالتالي، قد يعتقد شخص يقرأ هذا الكود أن الكود خاطئ ويحاول تحديثه:
def calculate_tax(income):
# tax rate is 20%
tax_rate = 0.25
return income * tax_rate
يجب علينا تجنب استخدام التعليقات عندما لا تكون ضرورية. لا تؤثر التعليقات على تنفيذ التعليمات البرمجية حيث يتجاهلها المترجم والمفسر. ومع ذلك، فهي جزء أساسي من قابلية قراءة التعليمات البرمجية. نحتاج إلى استخدامها بعناية كأداة لإضافة قوة إعلامية.
الآن يمكنك استخدام التعليقات في رحلتك مع بايثون
وهذا ما تحتاج إلى معرفته حول التعليق في بايثون!
بايثون هي واحدة من أكثر لغات البرمجة شيوعًا. من السهل تعلمها، لكن لا يمكنك تعلمها في يوم واحد. تحتاج إلى عملية تعلم مصممة جيدًا مع الكثير من الممارسة.
نقطة البداية هي العثور على مصدر جيد، وهو عنصر أساسي لرحلة تعلم فعّالة. حاول كتابة التعليمات البرمجية يوميًا. الاتساق هو المفتاح لمسار تعلم ناجح. فيما يلي بعض النصائح الإضافية التي ستساعدك في تسريع عملية التعلم الخاصة بك.
اكتشاف المزيد من بايثون العربي
اشترك للحصول على أحدث التدوينات المرسلة إلى بريدك الإلكتروني.