№28 Как писать комментарии / для начинающих
Добавление комментариев считается хорошей практикой. Это неисполняемые, но все равно важные части кода. Они не только помогают программистам, работающим над одним и тем же проектом, но также тестировщикам, которые могут обращаться к ним для ясности при тестировании белого ящика.
Куда лучше добавлять комментарии при создании или обновлении программы, иначе можно утратить контекст. Комментарии, добавленные позже, могут быть далеко не настолько эффективными.
Комментарии — это способ выражения того, что делает программа на самом высоком уровне. Это отмеченные строчки, которые комментируют код. В Python они бывают двух типов: одно- и многострочные.
Однострочные комментарии в Python
Такой тип комментариев нужен для написания простых, быстрых комментариев во время отладки. Такие комментарии начинаются с символа решетки # и автоматически заканчиваются символом окончания строки (EOL).
# Хороший код документируется print("Изучите Python шаг за шагом!")При добавлении комментария важно убедиться, что у него тот же уровень отступа, что и у кода под ним. Например, нужно оставить комментарий к строке объявления функции, у которой нет отступа. Однако они имеются у блоков кода внутри нее. Поэтому учитывайте выравнивание при комментировании внутренних блоков кода.
# Создадим список месяцев
months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul','Aug','Sep','Oct','Nov','Dec']
# Функция вывода календарных месяцев
def showCalender(months):
# Цикл for проходит по списку и вводит название каждого месяца
for month in months:
print(month)
showCalender(months)Многострочные комментарии в Python
Python позволяет писать комментарии на нескольких строках. Они называются многострочными или блочными. Такой тип комментирования подходит для описания чего-то более сложного.
Этот тип комментариев нужен для описания всего последующего кода. Дальше примеры многострочных комментариев в Python.
С помощью символа #
Для добавления многострочного комментария нужно начинать каждую строку с символа решетки и одного пробела. Такой комментарий можно разбить на абзацы. Для этого достаточно добавлять пустые строки с символом перед каждым из них.
Примечание: в оригинале этот символ (#) называется octothorpe, что переводится с латинского как «восемь концов». Термин придумала группа инженеров в Bell Labs, которая работала над проектом первой сенсорной клавиатуры.
# Чтобы выучить любой язык, вы должны следовать этим правилам.
# 1. Знать синтаксис, типы данных, структуры и условные операторы.
# 2. Изучить обработку ошибок и ввод/вывод.
# 3. Читайте о продвинутых структурах данных.
# 4. Пишите функции и следуйте концепциям ООП.
def main():
print("Начнем изучать Python.")Docstring в Python
В Python есть такая особенность, как задокументированные строки (docstring). С их помощью программисты могут быстро добавлять комментарии для каждого модуля, функции, метода или класса в Python.
Задать docstring можно с помощью строковой константы. Она обязана быть первой инструкцией в определении объекта.
У docstring более широкая область применения, чем у комментария. Она должна описывать, что делает функция, а не как. Хорошей практикой считается добавление таких строк в каждую функцию программы.
Как задать docstring в Python?
Задать docstring в Python можно с помощью тройных кавычек Нужно добавить один набор в начале и еще один – в конце. Docstring также могут занимать по несколько строк.
Примечание: строки с тремя кавычками также являются docstring в Python, пусть они и могут казаться обычными комментариями.
В чем отличие между комментарием и docstring?
Строки, начинающиеся с тройной кавычки, — это все еще обычные строки, которые могут быть написаны в несколько строк. Это значит, что они все еще являются исполняемыми инструкциями. Если же у них нет метки, значит сборщик мусора уничтожит их после исполнения.
Интерпретатор Python не будет игнорировать их так же, как комментарии. Но если такая строка расположена сразу же после объявления функции или класса в верхней части модуля, то она станет docstring. Получить к ним доступ можно следующим образом — myobj.__doc__ .
def theFunction():
'''
Эта функция демонстрирует использование docstring в Python.
'''
print("docstring python не являются комментариями.")
print("\nВыведем docstring функции. ")
print(theFunction.__doc__)Выводы
Комментарии и docstring добавляют ценности программе. Они делают программы более читаемыми и пригодными для последующей поддержки. Даже при рефакторинге сделать это будет намного проще с комментариями.
Разработка программного обеспечения — это лишь на 10% написание кода. Остальные 90% — поддержка.
Поэтому всегда добавляйте осмысленные комментарии и docstring, потому что они упрощают процесс взаимодействия и ускоряют процесс рефакторинга.
- ТЕГИ
- Уроки Python для начинающих
Многострочные комментарии в Python
Поддерживает ли Python многострочные комментарии так, как это реализовано в других языках? Какие варианты написания блочных комментариев в Python?
В большинстве языков программирования присутствует синтаксис для блочных комментариев, которые охватывают несколько строк текста, например C или Java:
/* Блочный комментарий. Охватывает несколько строк. */ int answer = 42; Есть ли в Python аналогичные многострочные комментарии? Короткий ответ: нет, по крайней мере, не совсем точно так же.
Python использует различные соглашения и синтаксис для блочных комментариев, которые охватывают несколько строк. В этой статье будут показаны некоторые варианты создания многострочных комментариев в Python.
Вариант 1: последовательные однострочные комментарии
Первым вариантом для комментирования нескольких строк кода в Python является простое использование # однострочного комментария для каждой строки:
# Это «блочный комментарий» в Python, сделанный # из нескольких однострочных комментариев. answer = 42 Большинство проектов Python следуют этому стилю, а руководство по стилю написания кода PEP 8 Python также рекомендует использовать повторяющиеся однострочные комментарии. Поэтому в большинстве случаях рекомендуется использовать их. Это также единственный способ написать «реальных» блочных комментариев в Python, которые игнорируется парсером.
Т.к. Python не поддерживает истинные многострочные комментарии, то для того чтобы закомментировать несколько строк кода требуется больше усилий. Приведём ряд полезных советов по ускорения работы с ними. У большинства редакторов кода есть шорткаты для блочных комментариев. Например, в Sublime Text достаточно просто выбирать пару строк, используя shift и клавиши курсора (или мышь), а затем нажимать cmd + /, чтобы закомментировать их все сразу.
Это даже работает в обратном порядке, то есть можно выбрать блок однострочных комментариев, и когда набирается клавиатурный шорткат cmd + /, весь блок снова раскомментируется.
Другие редакторы тоже поддерживают такую возможность: Atom, VS Code и даже Notepad++ имеют встроенные шорткаты для блочного комментирования в Python. Управление комментариями Python вручную – это неблагодарная работа, поэтому такая функция редактора может сэкономить много времени.
Вариант 2: использование многострочных строк вместо комментариев
Ещё одним вариантом для написания «правильных» многострочных комментариев в Python является использование многострочных строк с синтаксисом """ (три кавычки). Например:
""" Блок комментариев в Python, сделанный из многострочной строковой константы. """ answer = 42 Можно использовать тройные кавычки для создания чего-то, что напоминает многострочный комментарий в Python. Необходимо убедиться, что правильно ввели «"», иначе будет получено исключение SyntaxError. Например, если нужно определить блочный комментарий внутри функции с помощью такого синтаксиса, то должны выполнить это следующим образом:
def add_stuff(a, b): result = a + b """ Теперь возвращается результат. Ещё один пример многострочного комментария. """ return result Имейте в виду, что данный метод не создает «истинных» комментариев. Он просто вставляет текстовую константу, которая ничего не делает. Это то же самое, что вставить правильную однострочную строку где-то в коде и никогда не обращаться к ней.
Тем не менее, такая потерянная строковая константа не будет отображаться в байт-коде, фактически превращая её в многострочный комментарий. Далее доказательство того, что неиспользуемая строка не будет отображаться в дизассемблированном байт-коде CPython:
>>> import dis >>> dis.dis(add_stuff) 2 0 LOAD_FAST 0 (a) 2 LOAD_FAST 1 (b) 4 BINARY_ADD 6 STORE_FAST 2 (result) 8 8 LOAD_FAST 2 (result) 10 RETURN_VALUE Однако будьте осторожны, когда помещаете такие «комментарии» в код. Если строка следует сразу после сигнатуры функции, определения класса или в начале модуля, она превращается в docstring, которая имеет совсем другое значение в Python:
def add_stuff(a, b): """ Это теперь связанная с docstring функция с объектом функции и доступным как метаданные времени выполнения. """ result = a + b return result Docstrings («строки документации») позволяют сопоставлять удобочитаемую документацию с модулями, функциями, классами и методами Python. Они отличаются от комментариев исходного кода.
Комментарий удаляется парсером, тогда как docstring встраивается в байт-код и ассоциируется с документированием объекта. Её можно даже запросить к программному объекту во время выполнения.
Как это было сказано ранее, единственный способ получить «истинные» многострочные комментарии в Python, которые игнорируются парсером, заключается в использовании нескольких комментариев # для каждой однострочной строки.
Но в некоторых случаях использование тройных кавычек, может быть правильным выбором. Старайтесь избежать их использования в готовом к продашену коде.
Выводы
- В отличие от других языков программирования Python не поддерживает многострочные комментарии из коробки.
- Рекомендуемый способ закомментировать несколько строк кода в Python - использовать последовательные # однострочные комментарии. Это единственный способ получить «истинные» комментарии в исходном коде, которые удаляются парсером Python.
- Вы можете использовать строки с тремя кавычками «"», чтобы создать что-то похожее на многострочные комментарии в Python, но это не идеальный метод, и такие могут превратиться в случайные docstrings.
Комментарии в Python
Комментарии – способ прокомментировать код на ходу, на той же строке. Вот пример кода. Здесь, “Получил пользователя” – это комментарий.
user = get_user_by_id(...) # Получил пользователя Такие комментарии начинаются с символа # . Можно добавить комментарий на отдельной строке:
# Получил пользователя user = get_user_by_id(...) Комментарии ничего не делают, это просто заметки, которые можно оставлять прямо внутри программы.
Иногда программисты комментируют код, чтобы он перестал работать, но при этом не потерять его из виду:
# Получил пользователя # user = get_user_by_id(. )
Докстринги
Докстринг – строковая переменная, которая идёт сразу за объявлением функции, класса, метода или модуля. Она нужна для документирования всей функции: описания входящих параметров, результата, логики, крайних случаев. Заключается в тройные двойные кавычки. Вот так:
def tensorsolve(a, b, axes=None): """ Solve the tensor equation ``a x = b`` for x. It is assumed that all indices of `x` are summed over in the product, together with the rightmost indices of `a`, as is done in, for example, ``tensordot(a, x, axes=len(b.shape))``. """ В серьёзных проектах из них часто генерируется документация, поэтому они могут быть большими, по несколько экранов. Это касается проектов, у которых есть документация для разработчиков: Django, numpy, sqlalchemy.
Если проект не подразумевает, что им будут пользоваться другие разработчики, такого быть не должно. Длинных докстрингов не должно быть в скрипте ресайза изображений, сайте блога или алгоритме обучения нейронной сети.
Прямо в докстрингах можно писать короткие тесты, их называют доктесты. Ни разу не видел, чтобы кто-то это использовал в боевом проекте.
Как не использовать
Дублировать информацию из кода
Самая частая ошибка, связанная с комментариями: дублирование информации. В таком случае комментарий не несёт дополнительной информации, а просто переводит соседний код с Питона на русский/английский. Пример:
# загружаем данные из файла data.json with open('users.json', 'r') as handler: data = json.load(handler) Вот как можно исправить:
with open('users.json', 'r') as handler: data = json.load(handler) А так – ещё лучше:
data = load_all_users_from_file() Не поддерживать комментарии
Другая частая ошибка: не менять комментарии при изменении кода. В примере выше мы загружали данные из файла. Через месяц взялись за голову и поселили данные в базе данных. Код стал таким:
# загружаем данные из файла data.json data = db_session.query(User).all() Данные из файла? WAT?
Думать, что все поймут
Когда программист пишет кусок кода, он глубоко в него погружён: держит в голове все детали, связи и особые случаи. В таком состоянии всё поведение кажется понятным, поэтому разработчик может оставить комментарий самому себе. Проблема в том, что когда он переключится на другую задачу и забудет про детали, комментарий может взорвать мозг:
inv(strain_tensor) - rigidity.T # правый случай Правый, правда? Ну, теперь всё понятно.
Шутить
Шутки к неидеальному коду смотрятся неуместно. Представь, как чувствует себя разработчик, копающийся в чужом коде три часа и находящий новый модуль с заглавным комментарием оставь надежду, всяк сюда входящий . Не будь автором этого комментария. Лучше наведи порядок в своём коде.
Как использовать
Вот хорошие причины использовать комментарии:
- объяснить неочевидное поведение: бывает, что нужно объяснить какой-нибудь подводный камень куска кода или объяснить поведение в особом случае; использовать только если ту же информацию в коде поселить нельзя или очень сложно;
- оставить напоминание себе или коллеге: речь про комментарии вроде TODO: кешировать ответ ручки или FIXME: учитывать часовой пояс .
Прежде чем написать комментарий, попробуй поселить его в коде, указав параметр или дав подходящее название переменной.
Что изучать
- Доклад Григория Петрова про комментирование исходников. Обязателен к просмотру.
- PEP 257. ПЕП про докстринги.
- doctest. Документация к модулю про доктесты.
- What is the best comment in source code you have ever encountered?. Шутить в коде не стоит, а вот посмеяться с чужих шуток можно. Это ж не нам поддерживать.
Попробуйте бесплатные уроки по Python
Получите крутое код-ревью от практикующих программистов с разбором ошибок и рекомендациями, на что обратить внимание — бесплатно.
Переходите на страницу учебных модулей «Девмана» и выбирайте тему.
Однострочные и многострочные комментарии в Python
Комментарии — это пояснения к исходному тексту программы. Это может быть описание работы какого-то класса, функции или, например, значение переменной.
Чтобы ваш код был легко читаемым другими людьми, нужно придумывать очевидные имена, правильно подбирать названия функциям и правильно организовывать свой код.
Комментарии — это еще один способ сделать ваш код более читабельным. Они могут помочь не только другим людям читать и понимать ваш код, но и вам самим. Бывают ситуации, когда вы быстро пишете какой-то код, не комментируя ни строчки.
Разработчики часто забывают, как работает их собственный код. Особенно если он был написан давно.
Комментарии — это отличный способ быстро вспомнить свой код, написанный ранее.
Хороший комментарии должны быть:
- Уместными — не стоит указывать в комментариях очевидные вещи. К примеру, если вы назвали функцию print_black_list() , не нужно писать к ней комментарий # печать черного списка.
- Содержательными — должны четко описывать проблему, не должно возникнуть никаких запинок по поводу их понимания.
- Короткими — не нужно писать сочинение в комментариях.
- Актуальными — одна из проблем комментариев это их сопровождение. Код меняется, а обновлять комментарии часто забывают. Чем старше ваш комментарий, тем больше вероятность, что он лжет.
Плохой комментарий описывает код, отвечая на вопрос "что делает код?". Хороший комментарий отвечает на вопрос "зачем этот код?".
О том, как правильно писать комментарии, отлично написано в книге Роберта Мартина " Чистый код ", в главе 4 "Комментарии".
PEP 8 рекомендует использовать максимум 72 символа для комментариев на одной строке. Если ваш комментарий выходит за рамки 72 символов, его рекомендуется разделить на несколько строк.
О том, как создавать однострочные и многострочные комментарии в Python, разберем ниже.
Однострочные комментарии
Чтобы написать однострочный комментарий в Python, достаточно поставить " # " перед комментарием:
# Это однострочный комментарий print("python") # Это тоже однострочный комментарий
Python будет считать комментарием все, что находится после "#" и до конца строки.
Многострочные комментарии
Во многих языках программирования (например С++, Go, Java, JavaScript) можно создавать многострочные комментарии конструкцией вида /* */ В Python нет возможности создавать многострочные комментарии, и такая конструкция не сработает. Однако есть альтернативные решения.
Вариант #1 — писать однострочные комментарии друг за другом:
def multiline_comment_example(): # Это многострочный комментарий, оформленный # в виде однострочных комментариев, следующих # друг за другом
Вариант #2 — заключить комментарий в тройные кавычки:
""" Это многострочный комментарий, созданный с помощью тройных кавычек """
Второй вариант более удобен, но есть несколько нюансов, о которых нужно помнить.
- На самом деле это строка, которая не назначена какой-либо переменной. Эта строка не вызывается и ни на что не ссылается, поэтому может быть использована как многострочный комментарий.
- Если разместить такой комментарий сразу после определения функции или метода, Python будет считать его фрагментом документации, связанного с данной функцией/методом.
Многострочные комментарии, размещенные в определенных частях кода (например в самом начале модуля или сразу после объявления функции) могут служить документацией.