Комментарии в Python — однострочные, многострочные и лучшие практики

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

Однострочные комментарии

Однострочный комментарий начинается со знака решётки (#). Всё, что находится от # до конца строки, игнорируется интерпретатором.

# Calculate the area of a circle
radius = 5
area = 3.14159 * radius ** 2
print(area)  # outputs 78.53975

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

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

• Объясняйте почему было принято решение, а не что делает код (код сам показывает «что»).
• Отмечайте временные обходные решения: # TODO: replace with database lookup.
• Временно отключайте одну строку во время отладки.

# FIXME: division by zero if user_count is 0
average = total_score / user_count

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

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

# This function converts a temperature in Celsius to Fahrenheit.
# The formula is: F = (C * 9/5) + 32
# Returns a float rounded to two decimal places.
def celsius_to_fahrenheit(c):
    return round((c * 9 / 5) + 32, 2)

print(celsius_to_fahrenheit(100))  # 212.0
print(celsius_to_fahrenheit(0))    # 32.0

Большинство редакторов Python и IDE позволяют выделить несколько строк и переключить # сразу для всех (обычно Ctrl+/ или Cmd+/).

Docstrings — структурированные документирующие комментарии

В Python есть специальное соглашение по строковым литералам, называемое docstring (сокращение от documentation string). Docstring — это строка в тройных кавычках, помещённая непосредственно после заголовка def, class или модуля. Технически это не комментарий, а строковое выражение, но оно служит стандартным механизмом документирования и доступно во время выполнения через атрибут __doc__.

def greet(name):
    """Return a personalised greeting message.

    Args:
        name (str): The name of the person to greet.

    Returns:
        str: A greeting string.
    """
    return f"Hello, {name}!"

print(greet("Alice"))        # Hello, Alice!
print(greet.__doc__)         # prints the docstring above

Строки в тройных кавычках как блочные комментарии

Поскольку Python отбрасывает строковые литералы, которые не присваиваются ни одной переменной, строка в тройных кавычках, стоящая сама по себе (не в позиции def/class), иногда используется как неформальный блочный комментарий:

"""
This script processes the daily sales report.
It reads from sales.csv, aggregates by region,
and writes a summary to report.txt.
"""

import csv

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

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

Временное отключение кода с помощью комментариев — распространённый приём отладки:

def calculate_discount(price, rate):
    # discount = price * rate        # old flat-rate formula
    discount = price * rate if rate < 1 else price * (rate / 100)
    return price - discount

print(calculate_discount(100, 0.2))   # 80.0
print(calculate_discount(100, 20))    # 80.0

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

Специальные директивы в комментариях

Python и его инструменты распознают несколько строк-комментариев с машинно-читаемым смыслом:

Строка shebang

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

#!/usr/bin/env python3
# This line tells the OS to run the file with python3.

print("Hello from a standalone script!")

С точки зрения Python эта строка является комментарием (начинается с #), но операционная система использует её при непосредственном запуске файла (./script.py).

Объявление кодировки

Если исходный файл использует кодировку символов, отличную от UTF-8 (по умолчанию с Python 3), объявите её в первой или второй строке:

# -*- coding: utf-8 -*-

Python 3 по умолчанию использует UTF-8, поэтому сегодня это редко требуется, но вы можете встретить такую строку в устаревшем коде.

Директивы для проверки типов

Средства проверки типов, например mypy, учитывают специальные встроенные комментарии:

x = []  # type: ignore
result = some_function()  # type: ignore[return-value]

Они подавляют определённые ошибки типов, не изменяя поведения во время выполнения. Подробнее о том, как Python работает с типами, читайте в главе Python Variables.

Лучшие практики комментирования

Соблюдение этих соглашений сделает ваши комментарии по-настоящему полезными:

PEP 8 — официальное руководство по стилю Python — рекомендует:

• Встроенные комментарии должны отделяться от оператора как минимум двумя пробелами.
• Каждый встроенный комментарий должен начинаться с # (решётка, затем один пробел).
• Блочные комментарии, относящиеся к коду ниже, должны иметь тот же уровень отступа.

def apply_tax(price, tax_rate):
    # Tax rate is expressed as a decimal (e.g., 0.07 for 7 %).
    # Prices must be non-negative; validation happens upstream.
    tax = price * tax_rate
    return price + tax  # total including tax

Распространённые ошибки, которых следует избегать

1. Оставлять комментарии TODO без отслеживания

# TODO: handle the case where the file does not exist
data = open("data.txt").read()

TODO полезны во время разработки, но должны быть привязаны к системе отслеживания задач, а не оставаться бесконечно в производственном коде.

2. Комментировать большие блоки вместо их удаления

Система контроля версий (Git) сохраняет историю. Нет необходимости хранить закомментированный код для потомков — удалите его и обращайтесь к git log, если когда-нибудь понадобится его восстановить.

3. Непоследовательный стиль

Смешение #comment, # comment и ## comment в одном файле создаёт ощущение бесхозности кода. Договоритесь о стиле и применяйте его последовательно.

Итоги

Комментарии — это лёгкий инструмент, который окупается всякий раз, когда другой разработчик (или вы сами в будущем) читает ваш код. Для углублённого изучения смежных тем смотрите Python Syntax и Python Variables.

Practice