Поиск по сайту:

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

Введение

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

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

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

Предпосылки

У вас должен быть установлен Python 3 и настроена среда программирования на вашем компьютере или сервере. Если у вас не настроена среда программирования, вы можете обратиться к руководствам по установке и настройке среды программирования на вашем сервере, подходящей для вашей операционной системы (Ubuntu, CentOS, Debian и т. д.).

Синтаксис комментария

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

Информация: Чтобы следовать примеру кода в этом руководстве, откройте интерактивную оболочку Python в вашей локальной системе, выполнив команду python3. Затем вы можете копировать, вставлять или редактировать примеры, добавляя их после приглашения >>>.

Обычно комментарии выглядят примерно так:

# This is a comment

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

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

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

В списке комментарии могут выглядеть следующим образом:

# 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() из учебника How To Make a Simple Calculator Program in 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"
  )
...

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

Встроенные комментарии

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

Обычно встроенные комментарии выглядят так:

[code]  # Inline comment about the code

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

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

z = 2.5 + 3j  # Create a complex number

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

x = 8  # Initialize x with an arbitrary number

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

Комментирование кода для тестирования

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

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

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

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