При написании кода Python всегда рекомендуется делать его чистым и понятным. Организовать код, дать переменным и функциям описательные имена — вот несколько способов сделать это.

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

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

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

В этой статье рассматриваются основы написания комментариев в Python.

Написание комментариев на Python

Python игнорирует все, что написано в строке после решетки ( # ).

Комментарии могут быть добавлены в начале строки или встроены в другой код:

# This is a Python comment.
print("Hello World") # This is an inline Python comment.

Пробел после решетки не является обязательным, но он улучшит читаемость комментария.

Символ решетки в строковом литерале не указывает на начало строки комментария. Это просто символ решетки:

paragraph = "# Hash inside quotes is not a comment."

Comments should be at the same indent level as the code beneath it:

```py
def factorial(n):
  if n == 0:
    return 1
  else:
    # Use the factorial function
    return n * factorial(n-1)

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

Комментарии также полезны при отладке скрипта. Вместо удаления некоторых строк или блоков вы можете закомментировать их:

# for fruit in fruits:
#   print(fruit)

Многострочные комментарии в Python (блоки комментариев)

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

Самый простой способ написать многострочные комментарии в Python — это добавить однострочные комментарии один за другим:

# This is the first line.
# This is the second line.

Другой вариант — использовать строки документации .

Строки документации — это многострочные строковые литералы, которые используются для документирования того, что делает модуль, функция, класс или метод.

Строка документации начинается и заканчивается тройными двойными кавычками ( """ ) и может занимать одну или несколько строк:

"""This is
a multiline
docstring.
"""

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

Шебанг

Если вы читаете сценарии Python, вы можете заметить, что в некоторых из них первая строка начинается с символа #! символы и путь к интерпретатору Python:

#!/usr/bin/env python3

Эта последовательность символов называется shebang и используется для указания операционной системе, какой интерпретатор использовать для анализа остальной части файла. Сценарии, которые начинаются с shebang и являются исполняемыми, можно запускать в терминале, не вводя python перед именем сценария.

Поскольку строка shebang начинается с символа решетки, она рассматривается как комментарий и автоматически игнорируется интерпретатором Python.

Выводы

Написание комментариев является хорошей практикой и помогает другим разработчикам, в том числе будущим самим себе, понять, что делает код. В Python все, что находится после решетки ( # ) и до конца строки, считается комментарием.

Если у вас есть какие-либо вопросы или отзывы, не стесняйтесь оставлять комментарии.