Правила написания комментариев в коде Python

Раздел: Python -> Синтаксис и примеры

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

Основной способ комментирования

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

# Вывод приветствия
print('Привет, мир!')  # это тоже комментарий

комментарии кода python (комментарии в коде python)

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

Типичные проблемы:

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

Как создать однострочный комментарий?

Символ # ставится в начале комментария. Можно использовать как на отдельной строке, так и после кода.

x = 10  # присвоение значения переменной
# следующий блок выполняет суммирование
y = x + 5

Ошибка:

Если поставить # внутри строки, он станет частью строки, а не комментарием. Например, print('# не комментарий').

Как создать многострочный комментарий с помощью #?

Для многострочных комментариев ставят символ # в начале каждой строки.

# Это первая строка комментария
# Это вторая строка
# И третья

Такой способ явно выделяет каждую строку и соответствует рекомендациям PEP 8.

Проблема:

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

Использование строковых литералов в качестве многострочных комментариев

Некоторые разработчики применяют тройные кавычки (''' или """) для создания многострочных комментариев. Такой литерал, не присвоенный переменной, интерпретатор игнорирует, но он не является настоящим комментарием с точки зрения синтаксиса.

'''
Это многострочный блок, который выглядит как комментарий.
Интерпретатор воспринимает его как строку, но не использует.
'''
print('Код выполняется')

Данный метод удобен для быстрого отключения больших фрагментов кода, но не рекомендуется для постоянного комментирования: строка может быть сохранена в памяти (хотя обычно оптимизируется) и может случайно стать docstring.

Типичная ошибка:

Если такой блок окажется первым в функции или классе, он станет docstring и будет доступен через help(). Это может привести к непреднамеренному документированию.

Как документировать функции с помощью docstring?

Docstring - это строковый литерал в самом начале модуля, класса или функции, служащий для автоматической генерации документации. Хотя это не комментарий в узком смысле, он выполняет схожую функцию.

def add(a, b):
    '''Возвращает сумму двух чисел.'''
    return a + b

К docstring можно обратиться через add.__doc__ или help(add).

Проблема:

Часто путают docstring и комментарий. Комментарии не влияют на документацию, а docstring влияет. Docstring должен быть осмысленным и следовать стандартным конвенциям (например, PEP 257).

Как временно отключить блок кода (закомментировать)?

Для отладки или временного исключения фрагмента кода его заключают в комментарий. Самый простой способ - поставить # перед каждой строкой. Во многих редакторах есть комбинация клавиш (Ctrl+/ или Cmd+/).

# x = 10
# y = x * 2
# print(y)

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

'''
x = 10
y = x * 2
print(y)
'''

Однако такой способ может нарушить отступы или оставить строку в памяти.

Риск:

При двойном закомментировании (блок уже внутри тройных кавычек) может возникнуть синтаксическая ошибка из-за вложенных кавычек.

Как добавить пояснение в конце строки (inline комментарий)?

Комментарий можно разместить после исполняемого кода на той же строке, отделив его двумя пробелами и #.

total = price * quantity  # вычисление общей стоимости

Такие комментарии полезны для быстрого пояснения конкретного выражения.

Недостаток:

Строка может стать слишком длинной (>79 символов по PEP 8). Переносить код на следующую строку для комментария неудобно. Лучше выносить пояснение на отдельную строку сверху.

Расширенные примеры использования комментариев

Комментарии для разметки TODO и FIXME

В больших проектах принято оставлять пометки TODO, FIXME, HACK и т.д. Инструменты автоматически собирают такие комментарии.

Пример

# TODO: добавить проверку входных данных
# FIXME: исправить проблему с округлением
def calculate_discount(price):
    return price * 0.9

Аннотации типов как форма комментариев

Начиная с Python 3.5, аннотации типов улучшают читаемость, хотя не влияют на выполнение.

Пример

def greet(name: str) -> str:
    '''Возвращает приветствие.'''
    return f'Привет, {name}!'

print(greet('Анна'))

Привет, Анна!

Docstring в формате для Sphinx

Для автоматической генерации документации docstring оформляется в reStructuredText или Google style.

Пример

def power(base, exp):
    '''
    Возведение в степень.

    :param base: основание
    :type base: int or float
    :param exp: показатель степени
    :type exp: int
    :return: результат возведения
    :rtype: int or float
    '''
    return base ** exp

help(power)

Help on function power in module __main__:

power(base, exp)
    Возведение в степень.
    
    :param base: основание
    :type base: int or float
    :param exp: показатель степени
    :type exp: int
    :return: результат возведения
    :rtype: int or float

Закомментирование кода с помощью условного оператора

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

Пример

DEBUG = True  # переключатель отладки
if DEBUG:
    # print('Отладочное сообщение')
    x = 42
else:
    x = 0
print(x)

Многострочные комментарии с помощью конкатенации строк

Редкий приём: объединить несколько строк в одну строку, которая не используется, но занимает место.

Пример

_ = ('Этот текст интерпретатор прочитает как строку, '
     'но не сохранит, так как он не присвоен.')
print('Основной код')

Комментарии к регулярным выражениям

Сложные regexp можно разбивать на части и комментировать каждую.

Пример

import re
pattern = re.compile(r'''
    ^            # начало строки
    [0-9]{3}     # три цифры
    -?           # необязательный дефис
    [0-9]{2}     # две цифры
    $            # конец строки
''', re.VERBOSE)
print(pattern.match('123-45'))

<re.Match object; span=(0, 6), match='123-45'>

Использование комментариев для отключения части выражения

Можно закомментировать часть внутри функции, чтобы временно убрать аргумент.

Пример

result = func(arg1, arg2, #arg3
              arg4)
# arg3 временно исключён

Комментарии в коде Python - comments

комментарии кода python (python)