Комментарии в Python
Комментарии иногда могут помочь прояснить ваш код. В Python есть три типа комментариев (не официально, но фактически): блочные, встроенные и многострочные.
# Multiply savings by the annual interest rate savings = savings * 1.02
savings = savings * 1.02 # Multiply savings by the annual interest rate
“Многострочный комментарий” (использование docstrings не по назначению):
''' This here is a longer multi-line comment also known as docstring. ''' print("Yay") Комментирование кода в Python
Чтобы добавить комментарий в Python, используйте оператор хэштега # перед началом ввода комментария.
Прежде чем вдаваться в подробности, помните, что комментирование кода обычно вредно. Нужно стараться писать код, который выражает себя достаточно ясно, чтобы комментарии не требовались.
Давайте посмотрим на пример такого кода. Он реализует одномерное случайное блуждание. Как видите, код пестрит поясняющими комментариями.
import numpy as np import random def randwlk1d(n): x, y = 0, 0 # Generate the time points (tps) [1, 2, 3, . , n] tps = np.arange(n + 1) # Initialize positions array ps to the starting point y ps = [y] # Specify directions up and down (U and D) ds = ["U", "D"] for i in range(1, n + 1): # Randomly select either U or D (up or down) s = random.choice(ds) # Move the object up (U) or down (D) if s == "U": y += 1 elif s == "D": y -= 1 # Add each position to the ps list to track the positions ps.append(y) # Return timepoints and positions as (tps, ps) return tps, ps
Но что, если вместо комментариев к коду мы просто будем использовать более понятные имена переменных?
import numpy as np import random def randomwalk1D(n): x, y = 0, 0 timepoints = np.arange(n + 1) positions = [y] directions = ["UP", "DOWN"] for i in range(1, n + 1): step = random.choice(directions) if step == "UP": y += 1 elif step == "DOWN": y -= 1 positions.append(y) return timepoints, positions
Как видите, это существенно улучшает качество кода. Больше нет необходимости использовать комментарии, так как код говорит сам за себя.
Однако иногда полезно иметь возможность комментировать код. Итак, давайте посмотрим, какие виды комментариев существуют в Python.
Комментарии в Python и их типы
В Python комментарии начинаются с символа # . Официально в Python нет ни многострочных, ни встроенных комментариев. Однако есть три часто используемых способа их добавления:
- Одна строка перед кодом.
- В конце строки кода на той же линии.
- На нескольких строках с использованием тройных кавычек.
Вот неофициальные названия этих трех типов комментариев:
- Блочные комментарии
- Встроенные комментарии
- Многострочные комментарии или Docstrings.
Давайте рассмотрим каждый тип комментариев подробнее.
Блочные комментарии в Python
Блочный комментарий объясняет код, который следует за ним. Этот тип комментария обычно располагается на одну строку раньше того фрагмента кода, к которому он относится. Блочный комментарий обычно имеет отступ на одном уровне с кодом в следующей строке.
Пример блочного комментария:
# Multiply savings by the annual interest rate savings = savings * 1.02
Встроенные комментарии в Python
Встроенный комментарий – это комментарий на той же строке, что и код. Хотя это такой же комментарий, как и любой другой, разработчики называют его inline-комментарием.
Пример встроенного комментария:
savings = savings * 1.02 # Multiply savings by the annual interest rate
Многострочные комментарии в Python
Строка документации или docstring – это строка, созданная с помощью тройных кавычек «»» . Она используется для документирования кода путем размещения строки документации перед блоком кода. Это может быть однострочный комментарий или многострочный.
Примечание редакции: о создании многострочных строк и использовании тройных кавычек читайте в статье “Многострочная строка в Python”.
Но на самом деле многострочный комментарий не предназначен для использования в качестве собственно комментария. Вместо этого он используется как строка документации. В Python есть встроенная функция help() , которую можно вызвать для любого объекта Python. Если в этом объекте есть строка документации, функция help() покажет ее в консоли. Это может сэкономить вам время на погружение в документацию.
def greet(name): """ Greets a person with their name. """ print(f"Hello, ")
Теперь вы можете вызвать help() для метода greet() в любом месте, где он доступен:
Help on function greet in module __main__: greet(name) Greets a person with their name.
Под капотом docstring – это строковый литерал, который не игнорируется интерпретатором Python благодаря функции help() . Таким образом, docstring не может быть классифицирована как комментарий к коду. Вы без проблем можете использовать ее для комментирования кода, но это противоречит лучшим практикам.
Заключение
Старайтесь писать код, который достаточно читабелен, чтобы быть понятным и без комментариев. Но если вам необходимо написать комментарии, вы можете сделать это с помощью оператора хэштега # .
Если вам нужно добавить многострочные комментарии, следует использовать последовательные операторы # . Это связано с тем, что в Python нет многострочных комментариев. Халтурным способом добавления многострочных комментариев является использование docstring (строка в тройных кавычках), которая предназначена для документирования кода.
Перевод статьи Artturi Jalli “Comments in 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 будет считать его фрагментом документации, связанного с данной функцией/методом.
Многострочные комментарии, размещенные в определенных частях кода (например в самом начале модуля или сразу после объявления функции) могут служить документацией.