التعليقات في بايثون: سطر واحد، متعددة، وDocstrings

التعليقات مكتوبة للبشر لا للآلة

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

ومع ذلك، فالتعليق الذي يكرر ما يقوله الكود بوضوح لا فائدة منه. أفضل التعليقات هي تلك التي تشرح السبب — قيد معيّن، حل التفافي، أو قرار لا يظهر من الكود مباشرة. أما ما يحدث فالكود نفسه يخبرك به.

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

الصيغة الأبسط هي علامة # يتبعها ما تريد كتابته من ملاحظات:

تقدر كمان تضيف تعليق قصير في نهاية السطر. ومن المتعارف عليه إنك تترك على الأقل مسافتين قبل علامة #:

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

العلامة #section-2 الموجودة داخل النص هي جزء من عنوان URL. بايثون لا تتعامل مع # كبداية تعليق إلا بعد أن تنتهي السلسلة النصية.

تعطيل أسطر متعددة في بايثون

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

نادراً ما تكتب علامات # يدوياً. أي محرر أكواد محترم فيه اختصار «تبديل التعليق» (toggle line comment) يضيف أو يحذف # من جميع الأسطر المحددة دفعة واحدة:

• VS Code: Cmd + / على macOS أو Ctrl + / على Windows/Linux
• PyCharm: Cmd + / أو Ctrl + /
• Vim: يعتمد على الإضافات المثبتة؛ إضافة vim-commentary تربط gcc لتعليق سطر واحد و gc لتعليق تحديد كامل.

تعلّم الاختصار في محررك مرة واحدة، وبعدها «تعطيل كتلة أكواد كاملة لتجربة شيء ما» يصبح مسألة ضغطة زر واحدة.

حيلة النص ذو الاقتباس الثلاثي (ولماذا ليس تعليقاً حقيقياً)

أحياناً ستصادف أكواداً بهذا الشكل:

من الناحية التقنية، هذا مجرد تعبير نصي (string expression) يتم تجاهله. فبايثون تقرأه وتنفّذه ثم ترمي النتيجة. يبدو وكأنه تعليق، لكنه ليس كذلك فعليًا. ومن ناحية الأسلوب، هناك موضع واحد فقط يُستحسن فيه استخدام هذه الطريقة: وهو الـ docstring.

الـ docstring: المكان الوحيد الذي تنتمي إليه triple quotes

الـ docstring في بايثون عبارة عن نص محاط بعلامات اقتباس ثلاثية، يُوضع كأول جملة داخل دالة أو كلاس أو موديول. تتعرّف عليه بايثون باعتباره توثيقًا رسميًا، وتُتيحه أثناء التشغيل عبر الدالة help() وعبر الخاصية __doc__:

ميزتان تجعلان الـ docstring مميزًا:

1. الأدوات مثل محررات الأكواد ودالة help() ومولّدات التوثيق تقرؤه تلقائيًا، بينما التعليق العادي فوق الدالة لا يُقرأ بهذه الطريقة.
2. يصف الدالة عند موضع استدعائها — فحين يمرّر أحدهم المؤشر فوق discount(...) في محرره، يظهر الـ docstring مباشرة كتلميح.

وهناك اصطلاح متعارف عليه (PEP 257) لما يُكتب داخل الـ docstring: ملخّص من سطر واحد في البداية، ثم سطر فارغ، ثم وصف أطول إن دعت الحاجة. لكن لا تُشغل بالك كثيرًا بالشكل الدقيق في أول يوم — حتى سطر واحد بسيط أفضل بكثير من عدم كتابة docstring إطلاقًا.

ما الذي يقوله التعليق الجيد فعلًا؟

بعض الإرشادات التي ستوفّر عليك الكثير من الصداع لاحقًا:

• اشرح "لماذا" لا "ماذا". التعليق # Loop over the users ضوضاء لا قيمة لها، أما # Retry on 503 — Redis sometimes dies mid-deploy فهو تعليق ذهبي.
• حدِّث التعليقات عند تعديل الكود. التعليق الخاطئ أسوأ من غيابه، لأن التعليقات القديمة تُضلِّل من يقرأ الكود لاحقًا.
• لا تُعطّل أسطر الكود وتتركها كما هي. إن لم تعُد تحتاجها فاحذفها؛ نظام التحكم بالإصدارات (Git) يتذكّر كل شيء. الملف المليء بكتل معطّلة يفقد مصداقيته بسرعة.
• تجاوز الواضح. كتابة x = x + 1 # increment x لا تضيف شيئًا.

الخلاصة

التعليقات مجانية الكتابة ورخيصة التجاهل. استخدمها حين تريد ترك ملاحظة سيشكرك عليها القارئ — سببٌ خفيّ يجعل الكود يعمل، أو رابطٌ إلى مشكلة مُسجَّلة، أو تحذيرٌ من حالة استثنائية. واستخدم الـ docstring عند تعريف دالة أو كلاس. وفيما عدا ذلك، دع أسماء المتغيرات الواضحة والدوال الصغيرة تتحدث عن نفسها.

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