Создавайте комментарии Python правильно

Комментарии — это примечания, которые программисты добавляют к своему коду, чтобы объяснить, что этот код должен делать. Компиляторы или интерпретаторы, которые превращают код в действие, игнорируют комментарии, но они могут быть необходимы для управления программными проектами.

Комментарии помогают объяснить ваш код Python другим программистам и могут напомнить вам, почему вы сделали тот или иной выбор. Комментарии облегчают отладку и исправление кода, помогая будущим программистам понять варианты дизайна программного обеспечения.

Хотя комментарии в первую очередь предназначены для разработчиков, написание эффективных комментариев также может помочь в создании отличной документации для пользователей вашего кода. С помощью генераторов документов, таких как проекты Sphinx for Python, комментарии в вашем коде могут предоставлять содержимое для вашей документации.

Давайте заглянем под капот комментирования в Python.

Комментарии в Python

Согласно Руководству по стилю Python PEP 8, при написании комментариев следует помнить о нескольких вещах:

• Комментарии всегда должны быть полными и краткими предложениями.
• Лучше вообще не иметь комментария, чем если он будет трудным для понимания или неточным.
• Комментарии должны регулярно обновляться, чтобы отражать изменения в вашем коде.
• Слишком много комментариев может отвлекать и снижать качество кода. Комментарии не нужны, если цель кода очевидна.

В 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

В Python строки документации представляют собой многострочные комментарии, которые объясняют, как использовать данную функцию или класс. Документация вашего кода улучшается за счет создания высококачественных строк документации. При работе с функцией или классом и использовании встроенной функции help(obj) строки документации могут быть полезны для предоставления обзора объекта.

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

В приведенном выше коде строка документации предоставила подробную информацию о том, как работает связанная функция. С генераторами документации, такими как Sphinx, эту строку документации можно использовать, чтобы предоставить пользователям вашего проекта обзор того, как использовать этот метод.

Строка документации, определенная непосредственно под сигнатурой функции или класса, также может быть возвращена с помощью встроенной функции help() . Функция help() принимает имя объекта или функции в качестве аргумента и возвращает строки документации функции в качестве вывода. В приведенном выше примере можно вызвать help(get_person) для отображения строк документации, связанных с функцией get_person . Если вы запустите приведенный выше код в интерактивной оболочке, используя флаг -i , вы увидите, как Python будет анализировать эту строку документации. Запустите приведенный выше код, набрав python -i file.py

Вызов функции help(get_person) возвращает строку документации для вашей функции. Вывод содержит 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

Важно отметить, что, хотя многие IDE могут выделять эти комментарии для программиста, интерпретатор Python не рассматривает комментарии TODO иначе, чем блочные комментарии.

Лучшие практики написания комментариев Python

Существует ряд рекомендаций, которым следует следовать при написании комментариев, чтобы обеспечить их надежность и качество. Ниже приведены несколько советов по написанию качественных комментариев на Python.

Избегайте очевидного

Комментарии, утверждающие очевидное, не добавляют ценности вашему коду, и их следует избегать. Например:

 x = x + 4 # increase x by 4

Этот комментарий бесполезен, так как он просто указывает, что делает код, не объясняя, почему это нужно сделать. Комментарии должны объяснять «почему», а не «что» кода, который они описывают.

Переписанный более полезно, приведенный выше пример может выглядеть так:

 x = x + 4 # increase the border width

Делайте комментарии Python короткими и понятными

Ваши комментарии должны быть короткими и понятными. Они должны быть написаны стандартным текстом, а не псевдокодом, и должны заменить необходимость чтения фактического кода, чтобы получить общее представление о том, что он делает. Слишком много деталей или сложных комментариев не облегчают работу программиста. Например:

 # 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)

СУХОЙ и ВЛАЖНЫЙ

Когда вы пишете код, вы хотите придерживаться принципа СУХОЙ (не повторяйтесь) и избегать ВЛАЖНОГО (пишите все дважды).

Это справедливо и для комментариев. Избегайте использования нескольких операторов для описания кода и старайтесь объединять комментарии, объясняющие один и тот же код, в один комментарий. Однако при объединении комментариев важно соблюдать осторожность: небрежное объединение нескольких комментариев может привести к созданию огромного комментария, который нарушает руководства по стилю и за которым читателю будет трудно следовать.

Помните, что комментарии должны сокращать время чтения кода.

 # 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 Application Hosting может перенести ваш код из GitHub в облако за считанные секунды.