إن التعليقات comments والتوثيق documentation في الشيفرة المصدرية هي بأهمية الشيفرة البرمجية ذاتها، سبب ذلك هو أن عملية تطوير البرمجيات لا تنتهي أبدًا وتحتاج دائمًا للقيام بتغييرات، وذلك إما لإضافة ميّزات جديدة أو لإصلاح المشاكل، ولكن لا تستطيع تغيير الشيفرة إذا لم تفهمها لذا يجب ابقاءها بحالة صالحة للقراءة، كما كتب علماء الحاسوب هارولد ابلسون Harold Abelson وجيرالد جاي Gerald Jay وجولي سوسمان Julie Sussman:
اقتباس"يجب كتابة البرامج لكي يقرأها العالم بالمقام الأول ومن ثمّ لتنفذها الآلات".
تسمح لك التعليقات -بالإضافة إلى سلاسل التوثيق النصية docstrings وتلميح الأنواع type hints التي سنناقشها لاحقًا- بالمحافظة على وضوح الشيفرة، إذ أن التعليقات هي شروحات بلغة بشرية قصيرة وبسيطة تُكتب مباشرة في الشيفرة المصدرية ويتجاهلها الحاسوب، تقدم التعليقات ملاحظات مساعدة وتحذيرات ورسائل تذكير للآخرين الذين لم يكتبوا الشيفرة، أو أحيانًا لمبرمجين الشيفرة في المستقبل. سأل معظم المبرمجون أنفسهم في وقتٍ ما "من كتب هذه الفوضى الغير مقروءة؟" فقط ليأتي الجواب ضمن التعليقات "أنا!".
تركز هذه المقالة على التعليقات لتضمين التوثيق داخل الشيفرة الخاصة بك لجعلها أكثر ملائمة للقراءة، إن التوثيقات الخارجية مثل دليل المستخدم والدروس التعليمية على الشبكة والمراجع مهمة أيضًا إلا أنها خارج نطاق موضوعنا، إذا أردت أن تعرف أكثر بخصوص التوثيقات الخارجية راجع مولد توثيق سفينكس Sphinx.
ستتحدث المقالة أيضًا عن سلاسل التوثيق النصية docstrings هي نوع توثيق خاص بلغة بايثون للدوال functions والتوابع methods وأيضًا الوحدات modules الخاصة بك. عندما تحدد تعليقات بصيغة سلاسل التوثيق النصية، ستسهّل الأدوات الآلية automated tools، مثل مولدات التوثيق، أو وحدة help() المبنية مسبقًا في بايثون على المطورين إيجاد المعلومات عن الشيفرة الخاصة بك.
التعليقات 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 "اليونيكود العملي".
سلاسل التوثيق النصية Docstrings
سلاسل التوثيق النصية docstrings هي تعليقات بأسطر متعددة تظهر في أعلى ملف الوحدة المصدري ".py"، أو مباشرةً بعد تعليمة class، أو def، وتقدم توثيقات عن الوحدة module، أو الصنف class أو الدالة funtion) أو التوابع المعرّفة. تُستخدم أدوات توليد التوثيقات الآلية سلاسل التوثيق النصية هذه لإنشاء ملفات توثيق خارجية، مثل ملفات المساعدة، أو صفحات الويب.
يجب أن تستخدم سلاسل التوثيق النصية تعليقات متعددة الأسطر مع ثلاث علامات تنصيص مزودجة بدلًا من التعليقات أحادية السطر التي تبدأ بإشارة المربع #، كما ينبغي أن تستخدم سلاسل التوثيق النصية ثلاث علامات تنصيص مزودجة من أجل سلاسل ثلاثية الاقتباس بدلًا من ثلاث علامات تنصيص أحادية. إليك مثالًا عن ملف sessions.py في الوحدة الشهيرة requests:
1 # -*- coding: utf-8 -*- 2 """ requests.session ~~~~~~~~~~~~~~~~ This module provides a Session object to manage and persist settings across requests (cookies, auth, proxies). """ import os import sys --snip— class Session(SessionRedirectMixin): 3 """A Requests session. Provides cookie persistence, connection-pooling, and configuration. Basic Usage:: >>> import requests >>> s = requests.Session() >>> s.get('https://httpbin.org/get') <Response [200]> --snip-- def get(self, url, **kwargs): 4 r"""Sends a GET request. Returns :class:`Response` object. :param url: URL for the new :class:`Request` object. :param \*\*kwargs: Optional arguments that ``request`` takes. :rtype: requests.Response """ --snip--
يحتوي request الخاص بملف sessions.py على سلاسل توثيق نصية من أجل الوحدة (تعليق 2) والصنف Session (تعليق 3) وتابع get() الخاص بصنف Session (تعليق 4). لاحظ أنه على الرغم من أن سلسلة التوثيق النصية للوحدة يجب أن تكون أول سلسلة نصية تظهر في الوحدة، إلا أنها يجب أن تأتي بعد أي تعليق سحري، مثل سطر شيبانج shebang المبدوء بإشارة # أو تعريف الترميز (تعليق 1).
يمكن استرجاع سلاسل التوثيق النصية لاحقًا من أجل وحدة أو صنف أو تابع عن طريق التحقق من سمة الكائن __doc__ الخاصة به، إذ يمكننا هنا مثلًا فحص سلسلة التوثيق النصية لمعرفة المزيد عن وحدة sessions وصنف Session والتابع get():
>>> from requests import sessions >>> sessions.__doc__ '\nrequests.session\n~~~~~~~~~~~~~~~~\n\nThis module provides a Session object to manage and persist settings across\nrequests (cookies, auth, proxies).\n' >>> sessions.Session.__doc__ "A Requests session.\n\n Provides cookie persistence, connection-pooling, and configuration.\n\n Basic Usage::\n\n >>> import requests\n --snip-- >>> sessions.Session.get.__doc__ 'Sends a GET request. Returns :class:`Response` object.\n\n :param url: URL for the new :class:`Request` object.\n :param \\*\\*kwargs: --snip--
يمكن أن تستخدم أدوات التوثيقات الآلية سلاسل التوثيق النصية لتأمين معلومات مناسبة للسياق، ومن هذه الأدوات هي دالة help() المبنية مسبقًا في بايثون، والتي تعرض سلسلة التوثيق النصية للكائن الممرر بطريقة أسهل للقراءة من سلاسل __doc__ النصية المباشرة الخام، وهذا يفيد عند التعامل مع الصدفة التفاعلية interactive shell، لأننا نريد الحصول على المعلومات عن أي وحدة أو صنف أو دالة نريد استخدامها.
>> from requests import sessions >>> help(sessions) Help on module requests.sessions in requests: NAME requests.sessions DESCRIPTION requests.session ~~~~~~~~~~~~~~~~ This module provides a Session object to manage and persist settings -- More --
إذا كانت سلسة التوثيق النصية أكبر من أن تتسع على الشاشة تعرض بايثون --More-- في أسفل النافذة، ويمكنك الضغط على المفتاح الإدخال ENTER للوصول إلى السطر التالي أو ضغط على مفتاح spacebar للوصول إلى الصفحة التالية أو الضغط على مفتاح Q للخروج من مشاهدة سلسلة التوثيق النصية.
ينبغي أن تحتوي سلسلة التوثيق النصية عمومًا على سطر واحد يلخص الوحدة أو الصنف أو الدالة متبوعًا بسطر فارغ ومعلومات مفصلة أكثر، أما بالنسبة للتوابع والدوال، فيمكن أن تحتوي على معلومات عن المُعاملات والقيم المُعادة والآثار الجانبية الخاصة بها. نحن نكتب سلاسل التوثيقات النصية للمبرمجين الآخرين وليس لمستخدمي البرنامج، لذا يجب أن تحتوي معلومات تقنية وليس على دروسًا تعليمية.
تقدم سلاسل التوثيق النصية فائدةً ثانيةً مهمة، لأنها تضمّن التوثيقات في الشيفرة المصدرية، فعندما تكتب التوثيقات بصورةٍ منفصلة عن الشيفرة يمكن أن تنساها كاملة، وبدلًا عن ذلك عندما تكتب سلاسل التوثيق النصية في أعلى الوحدات والأصناف والدوال تبقى المعلومات سهلة المراجعة والتحديث.
ربما لا تكون قادرًا على كتابة سلاسل التوثيق النصية إذا ما زلت تعمل على الشيفرة التي تريد وصفها، ففي تلك الحالة أضف تعليق TODO في سلسلة التوثيق النصية بمثابة تذكير لإكمال التفاصيل المتبقية. مثلًا لدى الدالة الخيالية reverseCatPolarity() سلسلة توثيق نصية ضعيفة توضّح ما هو واضح أصلًا:
def reverseCatPolarity(catId, catQuantumPhase, catVoltage): """عكس قطبية قطّة TODO أنهِ سلسلة التوثيق النصية""" --snip--
ربما تغريك كتابة توثيقات قصيرة والمضي قدمًا لأن كل صنف ودالة وتابع يجب أن يكون لديه سلسلة توثيق نصية، إلا أنه من السهل نسيان أن سلسلة التوثيق النصية هذه ستحتاج لإعادة كتابة دون تعليق TODO.
يحتوي PEP257 على توثيق مفصل عن سلاسل التوثيق النصية.
ترجمة -وبتصرف- لقسم من الفصل COMMENTS, DOCSTRINGS, AND TYPE HINTS من كتاب Beyond the Basic Stuff with Python.
أفضل التعليقات
لا توجد أية تعليقات بعد
انضم إلى النقاش
يمكنك أن تنشر الآن وتسجل لاحقًا. إذا كان لديك حساب، فسجل الدخول الآن لتنشر باسم حسابك.