إن التعليقات comments والتوثيق documentation في الشيفرة المصدرية هي بأهمية الشيفرة البرمجية ذاتها، سبب ذلك هو أن عملية تطوير البرمجيات لا تنتهي أبدًا وتحتاج دائمًا للقيام بتغييرات، وذلك إما لإضافة ميّزات جديدة أو لإصلاح المشاكل، ولكن لا تستطيع تغيير الشيفرة إذا لم تفهمها لذا يجب ابقاءها بحالة صالحة للقراءة، كما كتب علماء الحاسوب هارولد ابلسون Harold Abelson وجيرالد جاي Gerald Jay وجولي سوسمان Julie Sussman:
اقتباس
“يجب كتابة البرامج لكي يقرأها العالم بالمقام الأول ومن ثمّ لتنفذها الآلات”.
تسمح لك التعليقات -بالإضافة إلى سلاسل التوثيق النصية docstrings وتلميح الأنواع type hints التي سنناقشها لاحقًا- بالمحافظة على وضوح الشيفرة، إذ أن التعليقات هي شروحات بلغة بشرية قصيرة وبسيطة تُكتب مباشرة في الشيفرة المصدرية ويتجاهلها الحاسوب، تقدم التعليقات ملاحظات مساعدة وتحذيرات ورسائل تذكير للآخرين الذين لم يكتبوا الشيفرة، أو أحيانًا لمبرمجين الشيفرة في المستقبل. سأل معظم المبرمجون أنفسهم في وقتٍ ما “من كتب هذه الفوضى الغير مقروءة؟” فقط ليأتي الجواب ضمن التعليقات “أنا!”.
تركز هذه المقالة على التعليقات لتضمين التوثيق داخل الشيفرة الخاصة بك لجعلها أكثر ملائمة للقراءة، إن التوثيقات الخارجية مثل دليل المستخدم والدروس التعليمية على الشبكة والمراجع مهمة أيضًا إلا أنها خارج نطاق موضوعنا، إذا أردت أن تعرف أكثر بخصوص التوثيقات الخارجية راجع مولد توثيق سفينكس Sphinx.
التعليقات Comments
تدعم بايثون تعليقات السطر الواحد والأسطر المتعددة مثل كل لغات البرمجة، أي نص يأتي بعد إشارة # ونهاية السطر هو تعليق سطر واحد، وعلى الرغم من أنه ليس لبايثون صياغة مخصصة لتعليقات الأسطر المتعددة يمكن استخدام السلاسل النصية المتعددة الأسطر بثلاث مزدوجات بدلًا عن ذلك، حيث لا تتسبب قيمة السلسلة النصية هذه بأن يقوم مفسر بايثون بأي شيء، انظر إلى هذا المثال:
# هذا تعليق سطري """هذه سلسلة نصية متعددة الأسطر وتعمل كتعليق متعدد الأسطر أيضًا """
إذا استمر التعليق الخاص بك لأكثر من سطر فمن الأفضل استخدام تعليق واحد متعدد الأسطر بدلًا من عدة تعليقات سطر واحد متتالية التي ستكون قراءتها أصعب كما نرى هنا:
"""هذه طريقة جيدة لكتابة تعليق يمتد لعدة أسطر """ # هذه ليست طريقة جيدة # لكتابة تعليق # يمتد لعدة أسطر.
تعدّ التعليقات والتوثيقات فكرة ثانوية في عملية البرمجة ويعتقد البعض بأنها تتسبب بالضرر أكثر من الإفادة، التعليقات ليست اختيارية إذا أردت كتابة شيفرة احترافية ومقروءة، سنكتب في هذا القسم تعليقات مفيدة تزيد معرفة القارئ دون أن تؤثر على قابلية قراءة البرنامج.
تنسيق التعليق
لننظر إلى بعض التعليقات التي تتّبع ممارسات تنسيق جيّدة:
1 # هنا تعليق بخصوص الشيفرة البرمجية التالية: someCode() 2 # هنا كتلة تعليق أطول تمتد إلى عدة أسطر # باستخدام عدّة تعليقات سطر واحد على التوالي 3 # # تُعرف هذه الكتل بكتل التعليقات if someCondition: 4 # هنا تعليق بخصوص الشيفرة البرمجية التالية 5 someOtherCode() # هنا تعليق سطري
يجب أن تكون التعليقات في سطرها الخاص بدلًا من نهاية سطر الشيفرة، يجب أن تكون التعليقات في معظم الوقت جمل كاملة سليمة الكتابة مع علامات الترقيم بدلًا من عبارات أو كلمات وحيدة (تعليق 1). الاستثناء هو أن التعليقات يجب أن تتبع لحدود طول السطر الواحد الخاص بالشيفرة المصدرية ذاته، ويمكن للتعليقات التي تمتد لأسطر متعددة أن تستخدم تعليقات سطر واحد متعددة على التوالي وذلك يُعرف بكتلة التعليقات block comments (تعليق 2). يمكننا فصل الفقرات في كتل تعليقات باستخدام فراغ وتعليق سطر واحد (تعليق 3). يجب للتعليقات أن تكون بمستوى مماثل للمسافة البادئة للشيفرة التي تُعلق عليها (تعليق 4). تُدعى التعليقات التي تتبع سطر الشيفرة بالتعليقات السطرية inline comments (تعليق 5) ويجب على الأقل ترك فراغين بين الشيفرة والتعليق.
يجب أن تحتوي تعليقات السطر الأحادي على فراغ واحد بعد إشارة #:
#لا تكتب التعليقات مباشرةً بعد إشارة التعليق
يمكن أن تحتوي التعليقات على رابط URL مع المعلومات المتعلقة به، إلا أنه لا يجب استبدال التعليقات بالروابط لأن المحتوى المتعلق بالرابط يمكن أن يختفي من الشبكة في أي وقت:
# إليك شرحًا مفصلًا عن بعض الجوانب في هذه الشيفرة البرمجية # والموجودة على الرابط التالي، لمزيد من المعلومات اذهب إلى https://example.com
تصف الاصطلاحات المذكورة سابقًا النمط أكثر من وصفها للمحتوى، إلا أنها تُسهِّل من قراءة التعليق، كلما كان التعليق أسهل للقراءة، زاد اهتمام المبرمجين فيها، وتكون التعليقات مفيدة فقط عندما يستطيع المبرمجون قراءتها.
التعليقات السطرية
تأتي التعليقات السطرية inline comments في نهاية سطر الشيفرة كما في الحالة التالية:
while True: # استمرّ بسؤال اللاعب لحين إدخاله لحركة صالحة
تكون التعليقات السطرية مختصرة، لذا يمكن أن تتسع ضمن حدود طول السطر الموضوعة في دليل تنسيق البرنامج، هذا يعني أنها في أغلب الأحوال تكون قصيرة لحد عدم إعطاء معلومات كافية. إذا كنت تريد استخدام التعليقات السطرية، فانتبه لجعل التعليق يشرح السطر الذي يسبقه فقط، يجب وضع التعليق السطري في سطره الخاص إذا كان يحتاج لمساحة أكثر أو كان يشرح أكثر من سطر من الشيفرة.
أحد الاستخدامات الشائعة المناسبة للتعليقات السطرية هو شرح هدف متغير ما أو إعطاء بعض من السياق بخصوصه، وتُكتب هذه التعليقات السطرية على تعبير الإسناد الذي يُنشئ المتغير:
TOTAL_DISKS = 5 # المزيد من الأقراص سيزيد صعوبة الأحجية
استخدام ثاني شائع للتعليقات السطرية هو إضافة سياق لقيم المتغيرات عندما تريد انشائها:
month = 2 # تتراوح قيمة الأشهر من 0 (أي يناير) إلى 11 (أي ديسمبر) catWeight = 4.9 # الوزن بوحدة الكيلوجرام website = 'inventwithpython.com' # لا تُضمّن "https://" في بداية القيمة
لا يجب على التعليقات السطرية أن تحدد نوع بيانات المتغير، لأن هذا واضح من تعبير الإسناد إلا أذا كان ذلك يشكل تعليقًا لتلميح النوع type hints وهو ما سنتحدث عنه لاحقًا.
التعليقات التوضيحية
يجب أن تشرح التعليقات بالعادة لماذا تكون الشيفرة مكتوبة بهذا الشكل بدلًا من طريقة عمل الشيفرة أو كيفية عملها، حتى مع تنسيق الشيفرة المناسب واصطلاحات التسميات المفيدة التي تحدثنا عنها سابقًا فلا يمكن للشيفرة شرح نوايا المبرمج، فقد تنسى تفاصيل الشيفرة التي كتبتها بعد أسابيع، بالتالي يجب عليك في الوقت الحاضر كتابة تعليقات شيفرة توضيحية لمنع نفسك المستقبلي من لعن نفسك الماضي.
لدينا هنا مثال عن تعليق غير مفيد يشرح ماذا تفعل الشيفرة بدلًا من تلميح سبب كتابة الشيفرة، إذ يوضح هذا التعليق أمرًا مفهومًا:
>>> currentWeekWages *= 1.5 # ضرب أجور الأسبوع الحالي بمقدار 1.5
إن هذا التعليق أكثر من غير مفيد، فمن الواضح من الشيفرة أن المتغير currentWeekWages مضروب بـالقيمة 1.5 لذا إهمال هذا التعليق بالكامل من شأنه تبسيط الشيفرة الخاصة بك. إن التعليق التالي سيكون أفضل بكثير:
>>> currentWeekWages *= 1.5 # أخذ نسبة الأجرة ونصف بالحسبان
يشرح هذا التعليق النيّة من هذه الشيفرة بدلًا من تكرار كيفية عمل الشيفرة، إذ يعطي سياقًا لا تستطيع حتى الشيفرة المكتوبة بشكل جيد تقديمها.
تعليقات الخلاصة
شرح نيّة المبرمج ليست الطريقة الوحيدة التي تكون فيها التعليقات مفيدة، تسمح التعليقات المختصرة التي تلخص عدة أسطر من الشيفرة للقارئ أن ينظر إلى الشيفرة بشكل سريع ويحصل على فكرة عامة عما تفعله. يستخدم المبرمجون عادة فراغ فارغ لفصل “فقرات” الشيفرة عن بعضها وتشغل تعليقات التلخيص summary comments سطرًا واحد في بداية هذه الفقرات، وعلى عكس التعليقات السطرية التي تشرح سطرًا واحدًا من الشيفرة، تصف تعليقات التلخيص ما تفعله الشيفرة على درجة أعلى من التجريد.
يمكن في هذا المثال أن نعرف من قراءة السطور الأربعة من الشيفرة أنها تضبط متغير playerTurn لقيمة تمثل اللاعب الضد، ولكن تعليق السطر الواحد القصير يريح القارئ من قراءة الشيفرة ومعرفة هدف القيام بذلك:
# تبديل الدور إلى اللاعب الآخر if playerTurn == PLAYER_X: playerTurn = PLAYER_O elif playerTurn == PLAYER_O: playerTurn = PLAYER_X
توزيع تعليقات خلاصة بالشكل هذا في البرنامج الخاص بك يُسهل علينا النظر إليه بشكل سريع، يمكن للمبرمج أن يتفحص الشيفرة بشكل دقيق بخصوص أي نقطة تهمه، وتمنع تعليقات الخلاصة المبرمجين من أخذ أفكار خاطئة عما تفعله الشيفرة، إذ يمكن لتعليق تلخيص قصير أن يؤكد أن المطور فهم بشكل مناسب كيفية عمل الشيفرة.
تعليقات “الدروس المستفادة”
طُلب مني عندما كنت أعمل في شركة برمجيات أن أُكيّف مكتبة رسوم بيانية لكي تتعامل مع تحديثات في الوقت الفعلي لملايين نقاط البيانات في المخطط. المكتبة التي كنا نستخدمها تستطيع إما تحديث المخطط في الوقت الفعلي أو تدعم مخططات لملايين نقاط البيانات ولكن ليس الأمرين معًا؛ توقعت أن أُنهي المهمة خلال بضعة أيام وفي الأسبوع الثالث مازلت اعتقد انني أستطيع ان انتهي خلال بضعة أيام، كل يوم كان الحل قريبًا جدًا وفي خلال الأسبوع الخامس كان لدي نموذج أولي يعمل.
خلال كل تلك الفترة تعلمت الكثير من التفاصيل عن كيفية عمل مكتبة الرسوم البيانية وما هي قدراتها وحدودها، ثم قضيت بضع ساعات اكتب هذه التفاصيل في تعليق بطول صفحة ووضعته في الشيفرة المصدرية، عرفت أن أي شخص يحتاج للتعديل على الشيفرة الخاصة بي لاحقًا سيواجه هذه المشاكل البسيطة نفسها التي واجهتها، وهذا التوثيق الذي كتبته سيوفر عليهم أسابيع من الجهد.
ربما يمتد تعليق “الدروس المستفادة” -كما اسميهم- لعدة فقرات مما يجعله يبدوا أنّه لا ينتمي إلى الشيفرة المصدرية ولكن المعلومات المحتواة فيه هي كنز لمن يحتاج المحافظة على هذه الشيفرة، لا تخف من كتابة تعليقات طويلة ومفصلة في الشيفرة المصدرية الخاصة بك لشرح كيفية عمل شيء ما، بالنسبة للمبرمجين الآخرين العديد من هذه التفاصيل ستكون غير معروفة أو غير مفهومة أو مهملة. يمكن لمطوري البرمجيات الذين لا يحتاجون لهذه التفاصيل بأن يتجاهلوها ببساطة، إلا أن المطورين الذين يحتاجونهم سيكونون ممتنين لوجودهم. تذكّر أن تعليق الدروس المستفادة هو ليس مثل توثيقات الوحدات أو الدوال (التي تتعامل معها سلاسل التوثيق النصية)، وهو ليس درس تعليمي لمستخدمي البرنامج، بل أن تعليقات الدروس المستفادة هي للمطورين الذين يقرؤون الشيفرة المصدرية.
لأن تعليق الدروس المستفادة الخاص بي يتعلق بمكتبة رسوم بيانية ذات مصدر مفتوح ويمكن أن يفيد الآخرين فقد نشرته في موقع السؤال والجواب العام Stackoverflow.org بحيث يتسنّى لللآخرين الذين هم في نفس حالتي إيجاده.
التعليقات القانونية
لدى بعض الشركات البرمجية أو المشاريع المفتوحة المصدر سياسات تضم حقوق النشر وترخيص البرمجيات ومعلومات عن المؤلف في التعليقات في أعلى كل ملف شيفرة مصدرية لأسباب قانونية، يجب أن تتألف هذه التوصيفات من عدة أسطر على الأكثر وتشبه التالي:
"""Cat Herder 3.0 Copyright (C) 2021 Al Sweigart. All rights reserved.
See license.txt for the full text."""
راجع إذا أمكن ملفات خارجية أو مواقع تحوي النص الكامل للرخصة بدلًا من ضم كل الرخصة فوق كل ملف شيفرة مصدرية، إنه من المتعب المرور عبر عدة صفحات من النصوص كلما تفتح ملف شيفرة مصدرية، وضم الرخصة كاملةً لا يضيف أي حماية قانونية إضافية.
تعليقات مهنية
أخبرني زميل أكبر مني أحترمه كثيرًا في عملي البرمجي الأول أننا إذا أرفقنا الشيفرة المصدرية لمنتجنا للعملاء أحيانًا فإنه من المهم أن تكون للتعليقات نبرة مهنية. يبدو وقتها أنني كتبت “يا إلهي ما هذا!” في أحد التعليقات لجزء مثير للإحباط من الشيفرة، شعرت عندئذٍ بالحرج واعتذرت مباشرةً وعدلت التعليق، ومنذ تلك اللحظة حافظت على مستوى المهنيّة الخاص بشيفرتي البرمجية حتى في المشاريع الشخصية.
ربما يُغريك كتابة مزحة أو التنفيس عن غضبك في تعليقات برنامجك، ولكن اعتد تجنّب القيام بذلك، فأنت لا تعرف من سيقرأ الشيفرة الخاص بك في المستقبل ومن السهل ألّا تُفهم نبرة النص، كما وضحنا سابقًا، السياسة الفُضلى هي كتابة تعليقاتك بطريقة مهذبة ومباشرة بدون مزاح.
تعليقات وسوم الشيفرة البرمجية والأشياء التي يجب القيام بها
يترك المبرمجين أحيانًا تعليقات قصيرة لتذكيرهم بخصوص المهام التي يجب القيام بها، ويأخذ ذلك شكل وسوم الشيفرة البرمجية codetags وهو تعليق بحروف كبيرة مثل TODO متبوع بشرح قصير، يجب استخدام أدوات إدارة المشروع في الحالة المثالية لمتابعة هذه المشاكل بدلًا من دفنها في الشيفرة المصدرية الخاصة بك، ولكن يمكن استخدام هذه التعليقات للمشاريع الشخصية الصغيرة التي لا تستخدم العديد من الأدوات، إذ يمكن لتعليق TODO أن يخدم كتذكير مفيد، كمثال على ذلك:
_chargeIonFluxStream() # TODO: النظر إلى سبب فشل هذه الدالة كل يوم ثلاثاء
بإمكانك استخدام عدد من وسوم الشيفرة لهذه التنبيهات كما يلي:
-
TODOيمثّل تذكيرًا عام عن عمل يجب القيام به -
FIXMEيمثّل تذكيرًا بخصوص عدم عمل جزء من الشيفرة بشكل كامل -
HACKيمثّل تذكيرًا بأن هذا الجزء من الشيفرة يعمل ولكن بصعوبة ويجب تطوير هذه الشيفرة -
XXXيمثّل تنبيهًا عامًا وعادةً ما يكون ذو ثقل كبيريجب إلحاق هذه التسميات ذات الحروف الكبيرة بشرح مفصل عن المهمة أو المشكلة، وبعدها يمكن البحث في الشيفرة المصدرية عن هذه التسميات لإيجاد الشيفرة التي بحاجة إصلاح، السيئة من هذه التعليقات أنه يمكن نسيان هذه التذكرات إن لم تكن تقرأ هذا القسم من الشيفرة الخاصة بك الموجودة فيها تلك الوسوم. لا يجب أن تستبدل وسوم الشيفرة أدوات متابعة المشاكل أو تقارير الأخطاء الرسمية. إذا أردت استخدام وسوم الشيفرة في الشيفرة الخاصة بك أنصح بإبقائها بسيطة باستخدام
TODOوتجاهل الباقي.
التعليقات السحرية وترميز الملف المصدري
لربما لمحت ملف مصدري .py مع شيء يشبه هذه الأسطر في أعلى الملف:
1 #!/usr/bin/env python3 2 # -*- coding: utf-8 -*-
تقدم هذه التعليقات السحرية magic comments التي تظهر دائمًا في أعلى الملف معلومات بخصوص المفسر أو الترميز، إذ يخبر سطر شيبانج shebang الأول المبدوء بإشارتي !# نظام التشغيل بالمفسر الذي يجب أن يُستخدم لتنفيذ التعليمات في الملف. التعليق السحري الثاني هو تعريف للترميز، ويُعرّف في هذه الحال الترميز UTF-8 كنمط ترميز يونيكود لاستخدامه في الملف المصدري. لا تحتاج على الإطلاق عمومًا لضم هذا السطر لأن معظم المحرّرات وبيئات التطوير المتكاملة IDEs تحفظ ملفات الشيفرة المصدرية باستخدام الترميز UTF-8، وتعامل إصدارات بايثون بدءًا من 3.0 الترميز UTF-8 كترميز الافتراضي. يمكن أن تحتوي الملفات المرمزة باستخدام UTF-8 على أي مَحرف لذا يبقى ملف المصدر .py صالحًا حتى لو كان يحتوي على حروف انكليزية أو صينية أو عربية. لمقدمة عن اليونيكود وترميز السلاسل النصية أرشح منشور مدوّنة نيد باتشيلدر Ned Batchelder “اليونيكود العملي”.
ترجمة -وبتصرف- لقسم من الفصل COMMENTS, DOCSTRINGS, AND TYPE HINTS من كتاب Beyond the Basic Stuff with Python.