Комментарии – это строки в компьютерных программах, которые игнорируются компиляторами и интерпретаторами. В этой статье мы разберем, как пишутся комментарии в коде на Python 3.
Использование комментариев может сделать код более читабельным для человека, поскольку они предоставляют дополнительную информацию или объяснение того, что делает каждая часть программы.
Комментируя свой код, вы можете помочь другим программистам, которые будут его читать, а также оставить заметки или напоминания себе самому.
В целом, лучше комментировать код при его написании или при обновлении программы. Через некоторое время после написания кода легко забыть ход своих мыслей, и комментарии, добавленные позже, могут оказаться менее полезными в долгосрочной перспективе.
Синтаксис комментариев в Python
Комментарии в Python начинаются со знака “решетки” (#) и символа пробела и продолжаются до конца строки.
Примечание. Чтобы опробовать примеры, откройте интерактивную оболочку Python, выполнив команду python3 в консоли. После этого можно будет копировать, вставлять или редактировать примеры, добавляя комментарии после >>>.
Как правило, комментарии выглядят примерно так:
# Это комментарий
Поскольку комментарии не выполняются, при запуске программы вы не увидите никаких признаков их наличия. Комментарии в коде предназначены для чтения людьми, а не для выполнения компьютерами.
В программе “Hello, World!” комментарий может выглядеть следующим образом:
# Вывести “Hello, World!” в консоль
print("Hello, World!")
А вот пример комментариев для перебора списка в цикле for:
# Определить переменную sharks как список строк sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem'] # Цикл for, который перебирает список sharks и выводит каждую строку for shark in sharks: print(shark)
Комментарии должны быть сделаны на том же уровне отступа, что и комментируемый код. То есть определение функции без отступа будет иметь комментарий без отступа, а на каждом последующем уровне отступа комментарии будут идти вровень с комментируемым кодом.
В следующем примере рассмотрим комментирование кода функции again(). Обратите внимание на расположение комментариев.
...
# Определить функцию again(), которая спрашивает пользователя, хочет ли он снова воспользоваться калькулятором
def again():
# Принять ввод от пользователя
calc_again = input('''
Do you want to calculate again?
Please type Y for YES or N for NO.
''')
# Если пользователь вводит Y, запустить функцию calculate()
if calc_again == 'Y':
calculate()
# Если пользователь вводит N, попрощаться и завершить программу
elif calc_again == 'N':
print('See you later.')
# Если пользователь нажмет другую клавишу, запустить функцию again
else:
again()
Комментарии оставляются в коде для помощи программистам, будь то автор кода или кто-то другой, кому случится работать с этим кодом. Если комментарии не могут должным образом поддерживаться и обновляться вместе с кодовой базой, лучше их не оставлять. В противном случае они со временем перестанут соответствовать коду и могут запутать читателя еще больше.
Комментируя код, нужно стремиться ответить на вопрос “почему”, а не “что” или “как”. Если только код не особенно сложен, то вы сможете понять, что и как он делает, просто читая его.
Блочные комментарии в Python 3
Блочные комментарии можно использовать для объяснения более сложного кода или кода, с которым, как вы ожидаете, читатель не будет знаком. Эти примечания более многословны и относятся к нескольким или всем последующим строкам кода. Располагаются они на том же уровне, что и код.
В блочных комментариях каждая строка начинается с “решетки” и одинарного пробела. Если необходимо использовать более одного абзаца, их следует разделять строкой, содержащей один знак #.
Вот пример блочного комментария, поясняющего, что происходит в функции main():
# The main function will parse arguments via the parser variable. These
# arguments will be defined by the user on the console. This will pass
# the word argument the user wants to parse along with the filename the
# user wants to use, and also provide help text if the user does not
# correctly pass the arguments.
def main():
parser = argparse.ArgumentParser()
parser.add_argument(
"word",
help="the word to be searched for in the text file."
)
parser.add_argument(
"filename",
help="the path to the text file to be searched through"
)
...
Блочные комментарии обычно используются в тех случаях, когда операции менее понятны и поэтому требуют подробного объяснения. Старайтесь избегать чрезмерного комментирования кода. Доверяйте способности других программистов понять ваш код, если только не пишете для определенной аудитории.
Встроенные комментарии
Встроенные комментарии располагаются в одной строке с кодом. Как и другие комментарии, они начинаются со знака # и пробела. Как правило, выглядит это так:
[код] # Встроенный комментарий, касающийся этого кода
Встроенные комментарии следует использовать редко. Они могут быть эффективны для объяснения сложных или запутанных частей кода. Также они пригодятся, если вы уверены, что в будущем не сможете вспомнить, почему написали строку кода именно так. Ну и конечно, их можно оставлять для коллег, которые, кто, как вы знаете, могут быть не знакомы со всеми аспектами вашего кода.
Например, если вы не используете много математики в своих программах на Python, вы или ваши коллеги могут не знать, что следующее действие создает комплексное число, поэтому можно добавить встроенный комментарий:
z = 2.5 + 3j # Создать комплексное число
Встроенные комментарии также можно использовать для объяснения причины, по которой что-то делается, или для дополнительной информации:
x = 8 # Инициализировать x случайным числом
Комментирование в строке следует использовать только в случае необходимости, когда это позволяет дать полезные указания для человека, читающего программу.
Комментирование как способ отключить часть кода
Основная функция комментариев – документирование кода. Но то, что комментарии пропускаются при выполнении программы, позволяет использовать их синтаксис для отключения частей кода. Это может пригодиться для тестирования или отладки создаваемой программы. То есть, когда вы сталкиваетесь с ошибками после добавления новых строк кода, вы можете закомментировать несколько из них, чтобы локализовать проблему.
Использование символа # также позволяет попробовать альтернативные варианты при настройке кода. Например, если вы не можете выбрать между циклом while и циклом for, можно попеременно отключать то один, то другой блок, сравнивая результаты.
import random
number = random.randint(1, 25)
# number_of_guesses = 0
for i in range(5):
# while number_of_guesses < 5:
print('Guess a number between 1 and 25:')
guess = input()
guess = int(guess)
# number_of_guesses = number_of_guesses + 1
if guess < number:
print('Your guess is too low')
if guess > number:
print('Your guess is too high')
if guess == number:
break
if guess == number:
print('You guessed the number!')
else:
print('You did not guess the number. The number was ' + str(number))
Комментирование кода с помощью символа # позволит вам опробовать различные методы программирования, а также поможет найти источник ошибки путем отключения разных частей кода.
Заключение
Комментирование помогает сделать ваши программы более читабельными для людей, в том числе и для вас самих. Добавление уместных и полезных примечаний может облегчить другим людям сотрудничество с вами в проектах.
Перевод статьи Lisa Tagliaferri “How To Write Comments in Python 3”.