Комментарии в программе Python

В этом руководстве вы узнаете, как добавлять комментарии в код. Вы изучите различные виды комментариев Python, включая блочные комментарии, встроенные комментарии и строку документации.

• Введение в комментарии Python
• Блочные комментарии в Python
• Встроенные комментарии Python
• Строки документации Python
• 1) Однострочные строки документации
• 2) Многострочные строки документации
• Многострочные комментарии Python
• Заключение

Введение в комментарии Python

Иногда вам нужно задокументировать код, который вы пишете. Например, вы можете отметить, почему работает тот или иной фрагмент кода. Для этого вы используете комментарии.

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

Python предоставляет три типа комментариев, включая блочный комментарий, встроенный комментарий и строку документации.

Блочные комментарии в Python

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

Чтобы создать блочный комментарий, вы начинаете с одного знака решетки(#), за которым следует один пробел и текстовая строка. Например:

# increase price by 5%
price = price * 1.05

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

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

Подобно блочному комментарию, встроенный комментарий начинается с одного знака решетки(#), за которым следует пробел и текстовая строка.

Следующий пример иллюстрирует встроенный комментарий:

salary = salary * 1.02   # increase salary by 2%

Строки документации Python

Строка документации — это строковый литерал, который вы помещаете в первые строки блока кода, например функции.

В отличие от обычного комментария, доступ к строке документации можно получить во время выполнения с помощью атрибута obj.__doc__, где obj — это имя функции. Обычно вы используете строку документации для автоматического создания документации по коду.

Строго говоря, строки документации не являются комментариями. Они создают анонимные переменные, ссылающиеся на строки. Кроме того, они не игнорируются интерпретатором Python.

Python предоставляет два типа строк документации: однострочные и многострочные.

1) Однострочные строки документации

Как следует из названия, однострочная строка документации соответствует одной строке в Python. Однострочная строка документации начинается с тройных кавычек(«»») и заканчивается тройными кавычками(«»»). Кроме того, ни до, ни после однострочной строки документации не будет пустых строк.

Следующий пример иллюстрирует однострочную строку документации в функции quicksort():

def quicksort():
""" sort the list using quicksort algorithm """
...

2) Многострочные строки документации

В отличие от однострочной строки документации, многострочная строка документации может охватывать несколько строк. Многострочная строка документации также начинается с тройных кавычек(«»») и заканчивается тройными кавычками(«»»).

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

def increase(salary, percentage, rating):
    """ increase salary base on rating and percentage
    rating 1 - 2 no increase
    rating 3 - 4 increase 5%
    rating 4 - 6 increase 10%
    """

Многострочные комментарии Python

Python не поддерживает многострочные комментарии.

Однако вы можете использовать многострочные строки документации в качестве многострочных комментариев. Это также рекомендовал Гвидо ван Россум, создатель Python.

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

Заключение

• При необходимости используйте комментарии для документирования вашего кода.
• Блочный комментарий и встроенный комментарий начинаются со знака решетки(#).
• Используйте строки документации для функций, модулей и классов.