Написание комментариев в Python 3
Python | Комментировать запись
Комментарии – это строки, которые существуют в коде программы, но игнорируются компиляторами и интерпретаторами. Комментарии делают код более удобочитаемым, так как позволяют предоставить пользователям дополнительную информацию или добавить объяснение того или иного блока кода.
В зависимости от цели программы комментарии могут служить в качестве примечаний. Также с их помощью вы можете объяснить другим программистам, что делает та или иная часть кода программы.
Комментарии в программу рекомендуется добавлять по мере написания или обновления кода, так как позже вы можете пропустить что-то важное.
Синтаксис комментариев
Комментарии в Python начинаются с хеша (символа #), после которого ставится пробел.
Общий вид комментария:
# This is a comment
Строки комментариев не выполняются, потому при запуске программы вы не увидите никаких признаков наличия в ней комментариев. Комментарии находятся в исходном коде для простоты чтения кода программы другими пользователями, а не для выполнения.
В простейшей программе «Hello, World!» комментарий может выглядеть так:
# Print “Hello, World!” to console
print("Hello, World!")
В цикле for, который итерирует списки, могут быть такие комментарии:
# Define sharks variable as a list of strings
sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem']
# For loop that iterates over sharks list and prints each string item
for shark in sharks:
print(shark)
При размещении комментария следует учитывать отступы в коде, для которого он предназначен. То есть, если определение функции не имеет отступов, то и комментарий к этому определению не должен иметь отступов.
Для примера рассмотрим функцию again() из руководства Написание простейшего калькулятора в Python 3:
...
# Define again() function to ask user if they want to use the calculator again
def again():
# Take input from user
calc_again = input('''
Do you want to calculate again?
Please type Y for YES or N for NO.
''')
# If user types Y, run the calculate() function
if calc_again == 'Y':
calculate()
# If user types N, say good-bye to the user and end the program
elif calc_again == 'N':
print('See you later.')
# If user types another key, run the function again
else:
again()
Комментарии должны помогать программистам работать с кодом. Если же по какой-либо причине вы не можете предоставить должную поддержку и своевременное обновление комментариев, лучше их вообще не использовать. Код без комментариев лучше, чем код с неправильными комментариями.
В комментарии рекомендуется указывать, почему этот код выполняет то или иное действие (а не как или что он делает). В большинстве случаев программист, ознакомившись с кодом, может сам определить, что именно выполняет код и каким образом он это делает.
Блочные комментарии
Блочные комментарии могут объяснить более сложный код или код, с которым пользователям будет трудно разобраться самостоятельно. Такой блок комментариев должен иметь столько же отступов, сколько блок кода, который он объясняет.
В блочных комментариях каждая строка начинается с хеша и пробела. Чтобы разделить блок комментариев на абзацы, поставьте с новой строки хеш и оставьте строку пустой.
Следующий блочный комментарий описывает действия функции 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"
)
...
Блочные комментарии обычно используются в случае, если код требует подробного объяснения. Однако следует избегать чрезмерного количества комментариев в коде программы.
Строчные комментарии
Строчные комментарии следуют за кодом (то есть, находятся в одной строке с теми выражениями, которые они объясняют).
Строчный комментарий выглядит так:
# Inline comment about the code
Строчные комментарии позволяют дать краткое объяснение для непонятной части кода, однако их нужно использовать с осторожностью. Часто их используют в качестве кратких примечаний для других пользователей.
Например, если вы предполагаете, что другие разработчики из вашей команды не знают, что следующее выражение создает комплексное число, вы можете добавить строчный комментарий:
z = 2.5 + 3j # Create a complex number
Также строчный комментарий может объяснить, почему вы используете здесь тот или иной элемент:
x = 8 # Initialize x with an arbitrary number
Строчные комментарии следует использовать крайне редко.
Комментирование кода перед тестированием
Кроме документации кода, комментарии также используются в тестировании программ. К примеру, так вы можете закомментировать ту часть кода, которую не нужно обрабатывать во время проверки программы. Если после внедрения нового кода программа выдаёт ошибки, вы можете закомментировать некоторые строки нового кода, чтобы узнать, в чём проблема.
Кроме того, комментарии позволяют вам добавить в код несколько альтернативных блоков и проверить, какой из них вам подходит больше. Например, вы можете добавить в программу цикл 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:
rint('You did not guess the number. The number was ' + str(number))
Читайте также:
С помощью символа # вы можете протестировать несколько вариантов кода, обнаружить ошибки или запустить только ту часть кода, которая нуждается в дополнительной проверке.
Заключение
Благодаря комментариям код программы становится удобочитаемым и понятным. Это упрощает взаимодействие других разработчиков с кодом ваших программ.
Читайте также: PEP 257
Tags: Python, Python 3