TOC

Как писать комментарии в Python 3

Вступление

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

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

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

Комментарии в Python начинаются с решетки (#) и пробела и продолжаются до конца строки.

Как правило, комментарии будут выглядеть примерно так: 

# This is a comment

Поскольку комментарии не выполняются, при запуске программы вы не увидите никаких признаков комментария. Комментарии содержатся в исходном коде для чтения людьми, а не для выполнения компьютерами.

В программе «Hello, World!» Комментарий может выглядеть так:

hello.py

# Print “Hello, World!” to console
print("Hello, World!")

Вfor loop, который повторяетlist, комментарии могут выглядеть так:

sharks.py

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

Комментарии должны быть сделаны в том же отступе, что и код, который он комментирует. То есть,function definition без отступа будет иметь комментарий без отступа, и каждый последующий уровень отступа будет иметь комментарии, которые выровнены с кодом, который он комментирует.

Например, вот как комментируется функцияagain() изHow To Make a Simple Calculator Program in Python 3 tutorial, с комментариями после каждого уровня отступа кода:

calculator.py

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

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

Комментируя код, вы должны стремиться ответить наwhy за кодом, а не наwhat илиhow. Если код не является особенно хитрым, просмотр кода может в целом сказать, что код делает или как он это делает.

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

В комментариях к блоку каждая строка начинается с хеш-метки и одного пробела. Если вам нужно использовать более одного абзаца, они должны быть разделены строкой, содержащей одну хеш-метку.

Вот пример комментария блока, который определяет, что происходит в функции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, если вы не пишете для определенной аудитории.

Встроенные комментарии появляются в той же строке оператора, следуя самому коду. Как и другие комментарии, они начинаются с хеш-метки и одного символа пробела.

Как правило, встроенные комментарии выглядят так: 

[code]  # Inline comment about the code

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

Например, если вы не используете многоmathв своих программах на Python, вы или ваши соавторы можете не знать, что следующее создает комплексное число, поэтому вы можете захотеть включить встроенный комментарий об этом: 

z = 2.5 + 3j  # Create a complex number

Встроенные комментарии также могут быть использованы для объяснения причины действия или дополнительной информации, например: 

x = 8  # Initialize x with an arbitrary number

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

Помимо использования комментариев в качестве способа документирования кода, хеш-метку можно также использовать для комментирования кода, который вы не хотите выполнять во время тестирования или отладки программы, которую вы сейчас создаете. То есть, когда вы сталкиваетесь с ошибками после внедрения новых строк кода, вы можете закомментировать некоторые из них, чтобы узнать, сможете ли вы устранить неполадку.

Использование хеш-метки также позволяет вам попробовать альтернативные варианты, пока вы решаете, как настроить свой код. Например, вы можете выбирать между использованием циклаwhile loop илиfor в игре Python и можете прокомментировать тот или иной цикл при тестировании и определении того, какой из них может быть лучшим:

guess.py

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

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

Заключение

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

Отсюда вы можете прочитать о PythonDocstrings in PEP 257, чтобы предоставить вам больше ресурсов для правильного документирования ваших проектов Python.

Related