أنشئ تعليقات بايثون بالطريقة الصحيحة

التعليقات عبارة عن ملاحظات يقوم المبرمجون بإعلانها على أكوادهم لشرح ما يفترض أن يفعله هذا الرمز. يتجاهل المترجمون أو المترجمون الفوريون الذين يحولون الكود إلى عمل التعليقات ، لكن يمكن أن تكون ضرورية لإدارة مشاريع البرامج.

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

على الرغم من أن التعليقات مخصصة للمطورين في المقام الأول ، إلا أن كتابة تعليقات فعالة يمكن أن تساعد أيضًا في إنتاج وثائق ممتازة لمستخدمي التعليمات البرمجية الخاصة بك. بمساعدة مولدات المستندات مثل Sphinx لمشاريع Python ، يمكن أن توفر التعليقات في التعليمات البرمجية محتوى لوثائقك.

دعونا ننظر إلى ما وراء غطاء التعليق في بايثون.

تعليقات في بايثون

وفقًا لـ Python PEP 8 Style Guide ، هناك العديد من الأشياء التي يجب وضعها في الاعتبار أثناء كتابة التعليقات:

• يجب أن تكون التعليقات دائمًا جمل كاملة ومختصرة.
• من الأفضل ألا يكون لديك أي تعليق على الإطلاق من تعليق يصعب فهمه أو غير دقيق.
• يجب تحديث التعليقات بانتظام لتعكس التغييرات في التعليمات البرمجية الخاصة بك.
• قد تؤدي التعليقات الكثيرة جدًا إلى تشتيت الانتباه وتقليل جودة الكود. التعليقات ليست ضرورية عندما يكون الغرض من الكود واضحًا.

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

التعليقات المضمنة

تقدم التعليقات المضمنة أوصافًا قصيرة للمتغيرات والعمليات البسيطة وتتم كتابتها على نفس السطر مثل بيان الكود:

 border = x + 10 # Make offset of 10px

يشرح التعليق وظيفة الكود في نفس بيان الكود.

منع التعليقات

تستخدم تعليقات الكتلة لوصف المنطق المعقد في الكود. يتم إنشاء تعليقات الحظر في Python بشكل مشابه للتعليقات المضمنة - والفرق الوحيد هو أن تعليقات الكتلة تتم كتابتها في سطر منفصل:

 import csv from itertools import groupby # Get a list of names in a sequence from the csv file with open('new-top-firstNames.csv') as f: file_csv = csv.reader(f) # Skip the header part: (sr, name, perc) header = next(file_csv) # Only name from (number, name, perc) persons = [ x[1] for x in file_csv] # Sort the list by first letter because # The groupby function looks for sequential data. persons.sort(key=lambda x:x[0]) data = groupby(persons, key=lambda x:x[0]) # Get every name as a list data_grouped = {} for k, v in data: # Get data in the form # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]} data_grouped[k] = list(v)

لاحظ أنه عند استخدام تعليقات الحظر ، تتم كتابة التعليقات أعلى الكود الذي يشرحونه. يفرض دليل أسلوب Python PEP8 أن سطر التعليمات البرمجية يجب ألا يحتوي على أكثر من تسعة وسبعين حرفًا ، وغالبًا ما تدفع التعليقات المضمنة الأسطر فوق هذا الطول. هذا هو السبب في كتابة تعليقات الكتلة لوصف الكود في سطور منفصلة.

تعليقات متعددة الأسطر

لا تدعم Python في الأصل التعليقات متعددة الأسطر ، مما يعني أنه لا يوجد شرط خاص لتعريفها. على الرغم من ذلك ، غالبًا ما يتم استخدام التعليقات التي تمتد عبر أسطر متعددة.

يمكنك إنشاء تعليق متعدد الأسطر من عدة تعليقات أحادية السطر عن طريق تقديم كل سطر بـ # :

 # interpreter # ignores # these lines

يمكنك أيضًا استخدام بناء جملة سلاسل متعددة الأسطر. في Python ، يمكنك تحديد سلاسل متعددة الأسطر من خلال تضمينها في """ أو علامات اقتباس مزدوجة ثلاثية أو علامات اقتباس مفردة ثلاثية ''' :

 print("Multi-Line Comment") """ This String is Multi line """

في الكود أعلاه ، لم يتم تعيين السلسلة متعددة الأسطر إلى متغير ، مما يجعل السلسلة تعمل مثل التعليق. في وقت التشغيل ، تتجاهل Python السلسلة ، ولا يتم تضمينها في الرمز الثانوي. ينتج عن تنفيذ الكود أعلاه المخرجات التالية:

 Multi-Line Comment

تعليقات خاصة

بالإضافة إلى جعل الكود الخاص بك قابلاً للقراءة ، فإن التعليقات تخدم أيضًا بعض الأغراض الخاصة في Python ، مثل التخطيط لإضافات الكود في المستقبل وإنشاء الوثائق.

تعليقات Python Docstring

في لغة Python ، تعتبر docstrings عبارة عن تعليقات متعددة الأسطر تشرح كيفية استخدام وظيفة أو فئة معينة. تم تحسين توثيق الكود الخاص بك عن طريق إنشاء سلاسل مستندات عالية الجودة. أثناء العمل مع وظيفة أو فئة واستخدام وظيفة help(obj) ، قد تكون docstrings مفيدة في إعطاء نظرة عامة على الكائن.

يوفر Python PEP 257 طريقة قياسية للتصريح عن سلاسل المستندات في Python ، كما هو موضح أدناه:

 from collections import namedtuple Person = namedtuple('Person', ['name', 'age']) def get_person(name, age, d=False): """ Returns a namedtuple("name", "age") object. Also returns dict('name', 'age') if arg `d` is True Arguments: name – first name, must be string age – age of person, must be int d – to return Person as `dict` (default=False) """ p = Person(name, age) if d: return p._asdict() return p

في الكود أعلاه ، قدم docstring تفاصيل حول كيفية عمل الوظيفة المرتبطة. باستخدام مولدات التوثيق مثل Sphinx ، يمكن استخدام سلسلة docstring هذه لمنح مستخدمي مشروعك نظرة عامة على كيفية استخدام هذه الطريقة.

يمكن أيضًا إرجاع سلسلة docstring المحددة أسفل الوظيفة أو توقيع الفئة باستخدام وظيفة help() المضمنة. تأخذ وظيفة help() اسم كائن أو دالة كوسيطة ، وترجع سلاسل مستندات الوظيفة كإخراج. في المثال أعلاه ، يمكن استدعاء help(get_person) للكشف عن سلاسل المستندات المرتبطة بوظيفة get_person . إذا قمت بتشغيل الكود أعلاه في غلاف تفاعلي باستخدام العلامة -i ، يمكنك أن ترى كيف سيتم تحليل هذا docstring بواسطة Python. قم بتشغيل الكود أعلاه عن طريق كتابة python -i file.py

تقوم استدعاء دالة help(get_person) بإرجاع سلسلة docstring لوظيفتك. يحتوي الإخراج على get_person(name, age, d=False) ، وهو توقيع دالة تضيفه Python تلقائيًا.

يمكن أيضًا استخدام السمة get_person.__ doc__ لاسترداد وتعديل سلاسل المستندات برمجيًا. بعد إضافة "بعض المعلومات الجديدة" في المثال أعلاه ، تظهر في المكالمة الثانية help(get_person) . ومع ذلك ، فمن غير المحتمل أنك ستحتاج إلى تغيير سلاسل المستندات ديناميكيًا في وقت التشغيل مثل هذا.

تعليقات TODO

عند كتابة التعليمات البرمجية ، هناك مناسبات تريد فيها إبراز سطور معينة أو كتل كاملة للتحسين. يتم تمييز هذه المهام بواسطة تعليقات TODO. تكون تعليقات TODO في متناول يديك عندما تخطط لتحديثات أو تغييرات على التعليمات البرمجية الخاصة بك ، أو إذا كنت ترغب في إبلاغ مستخدمي المشروع أو المتعاونين بأن أقسامًا معينة من رمز الملف لا تزال قيد الكتابة.

لا ينبغي كتابة تعليقات TODO على أنها كود زائف - يجب عليهم فقط شرح وظيفة الكود غير المكتوب بإيجاز.

تعليقات TODO وتعليقات الكتلة أحادية السطر متشابهة جدًا ، والفرق الوحيد بينهما هو أن تعليقات TODO يجب أن تبدأ ببادئة TODO:

 # TODO Get serialized data from the CSV file # TODO Perform calculations on the data # TODO Return to the user

من المهم ملاحظة أنه على الرغم من أن العديد من IDEs يمكنها إبراز هذه التعليقات للمبرمج ، فإن مترجم Python لا يعرض تعليقات TODO بشكل مختلف عن تعليقات الحظر.

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

هناك عدد من أفضل الممارسات التي يجب اتباعها عند كتابة التعليقات لضمان الموثوقية والجودة. فيما يلي بعض النصائح لكتابة تعليقات عالية الجودة بلغة بايثون.

تجنب ما هو واضح

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

 x = x + 4 # increase x by 4

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

إعادة الكتابة بشكل أكثر فائدة ، قد يبدو المثال أعلاه كما يلي:

 x = x + 4 # increase the border width

اجعل تعليقات بايثون قصيرة وحلوة

اجعل تعليقاتك قصيرة وسهلة الفهم. يجب أن تكون مكتوبة بالنثر القياسي ، وليس الكود الزائف ، ويجب أن تحل محل الحاجة إلى قراءة الكود الفعلي للحصول على نظرة عامة عامة على ما تفعله. الكثير من التفاصيل أو التعليقات المعقدة لا تجعل عمل المبرمج أسهل. علي سبيل المثال:

 # return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r) def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

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

 # return area of cylinder def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

استخدم المعرفات بعناية

يجب استخدام المعرفات بعناية في التعليقات. يمكن أن يؤدي تغيير أسماء المعرفات أو الحالات إلى إرباك القارئ. مثال:

 # return class() after modifying argument def func(cls, arg): return cls(arg+5)

يشير التعليق أعلاه إلى class argument ، ولم يتم العثور على أي منهما في الكود. يمكن إعادة كتابة هذا التعليق على النحو التالي:

 # return cls() after modifying arg def func(cls, arg): return cls(arg+5)

جاف ورطب

عندما تكتب رمزًا ، فأنت تريد الالتزام بمبدأ DRY (لا تكرر نفسك) وتجنب WET (اكتب كل شيء مرتين).

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

تذكر أن التعليقات يجب أن تقلل من وقت قراءة الكود.

 # function to do x work def do_something(y): # x work cannot be done if y is greater than max_limit if y < 400: print('doing x work')

في الكود أعلاه ، التعليقات مجزأة بشكل غير ضروري ، ويمكن دمجها في تعليق واحد:

 # function to do x if arg:y is less than max_limit def do_something(y): if y in range(400): print('doing x work')

مسافة بادئة متسقة

تأكد من وضع مسافة بادئة للتعليقات على نفس مستوى الكود الذي يصفونه. عندما لا يكونون كذلك ، قد يكون من الصعب متابعتهم.

على سبيل المثال ، لا يتم وضع مسافة بادئة لهذا التعليق أو وضعه بشكل صحيح:

 for i in range(2,20, 2): # only even numbers if verify(i): # i should be verified by verify() perform(x)

يمكن إعادة كتابتها على النحو التالي:

 # only even numbers for i in range(2,20, 2): # i should be verified by verify() if verify(i): perform(x)

ملخص

التعليقات هي عنصر مهم في كتابة كود مفهوم. الاستثمار الذي تقوم به في كتابة تعليق هو الاستثمار الذي ستقدره بنفسك في المستقبل - أو المطورين الآخرين الذين يحتاجون للعمل على قاعدة التعليمات البرمجية الخاصة بك. يتيح لك التعليق أيضًا اكتساب رؤى أعمق في التعليمات البرمجية الخاصة بك.

في هذا البرنامج التعليمي ، تعلمت المزيد حول التعليقات في Python ، بما في ذلك الأنواع المختلفة من تعليقات Python ، ومتى تستخدم كل منها ، وأفضل الممارسات التي يجب اتباعها عند إنشائها.

كتابة التعليقات الجيدة هي مهارة يجب دراستها وتطويرها. للتدرب على كتابة التعليقات ، فكر في الرجوع وإضافة التعليقات إلى بعض مشاريعك السابقة. للإلهام ولرؤية أفضل الممارسات أثناء العمل ، تحقق من مشاريع Python الموثقة جيدًا على GitHub.

عندما تكون جاهزًا لإطلاق مشاريع Python الخاصة بك ، يمكن لمنصة استضافة التطبيقات في Kinsta الحصول على الكود الخاص بك من GitHub إلى السحابة في ثوانٍ.