Комментарии в Python — однострочные, многострочные и docstring

Введение

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

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

Однострочный комментарий в Python начинается с символа #. Всё, что идёт после # до конца строки, интерпретатор Python игнорирует.

# Это однострочный комментарий
print("Привет, мир!")  # Комментарий после кода

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

Правила оформления по PEP 8

Стандарт PEP 8 задаёт рекомендации по оформлению комментариев:

• Комментарий начинается с #, за которым следует один пробел
• Инлайн-комментарии (в конце строки) отделяются от кода минимум двумя пробелами
• Комментарий должен быть законченным предложением с заглавной буквы

# Правильно: пробел после #
x = 10  # Задаём начальное значение

#Неправильно: нет пробела после #
x = 10 #Слишком близко к коду

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

Однострочные комментарии полезны, когда нужно:

• Объяснить неочевидную логику
• Указать причину выбора конкретного решения
• Оставить пометку TODO или FIXME

# TODO: оптимизировать алгоритм для больших массивов
def search(data, target):
    # Используем линейный поиск, так как данные не отсортированы
    for item in data:
        if item == target:
            return True
    return False

# FIXME: обработать случай пустого списка
def get_average(numbers):
    return sum(numbers) / len(numbers)

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

В Python нет отдельного синтаксиса для многострочных комментариев, как, например, /* ... */ в C или Java. Однако есть два распространённых способа создать комментарий из нескольких строк.

Несколько однострочных комментариев подряд

Самый распространённый и рекомендуемый способ — использовать несколько строк с #:

# Этот блок кода отвечает за подключение к базе данных.
# Сначала проверяем доступность хоста,
# затем устанавливаем соединение с таймаутом 30 секунд.
connection = connect(host, timeout=30)

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

Другой способ — использовать строковый литерал с тройными кавычками (""" или '''). Если такая строка не присвоена переменной, Python создаёт строковый объект, но тут же его удаляет:

"""
Этот блок временно закомментирован
для отладки проблемы с авторизацией.
Вернуть после исправления бага #1234.
"""

Важно понимать, что это не настоящий комментарий — это строковый литерал, который Python обрабатывает как выражение. Использовать тройные кавычки для комментирования больших блоков кода удобно при отладке, но в production-коде лучше применять #.

Углубить понимание основ Python и научиться писать чистый, хорошо документированный код поможет практика. Если вы хотите детальнее изучить Python с нуля — приходите на наш большой курс Основы Python. На курсе 209 уроков и 34 упражнения, AI-тренажёры для практики 24/7, решение задач с живым ревью наставника, еженедельные встречи с менторами.

Docstring — строки документации

Docstring (documentation string) — это специальная строка, которая размещается в начале модуля, класса, метода или функции. В отличие от обычных комментариев, docstring сохраняется в атрибуте __doc__ объекта и доступна во время выполнения программы.

Синтаксис docstring

Docstring оформляется тройными кавычками и располагается сразу после объявления:

def greet(name):
    """Возвращает приветственное сообщение для указанного имени."""
    return f"Привет, {name}!"

Для доступа к docstring используется атрибут __doc__ или встроенная функция help():

print(greet.__doc__)
# Вывод: Возвращает приветственное сообщение для указанного имени.

help(greet)
# Выведет справку по функции, включая docstring

Однострочный docstring

Если описание умещается в одну строку, открывающие и закрывающие кавычки располагаются на одной строке:

def square(n):
    """Возвращает квадрат числа n."""
    return n ** 2

Многострочный docstring

Для сложных функций и классов используется многострочный формат. Первая строка — краткое описание, затем пустая строка и развёрнутое описание:

def fetch_data(url, timeout=30, retries=3):
    """Загружает данные по указанному URL.

    Выполняет HTTP GET-запрос с заданным таймаутом.
    При неудаче повторяет запрос указанное количество раз.

    Args:
        url: Адрес для загрузки данных.
        timeout: Максимальное время ожидания в секундах.
        retries: Количество повторных попыток при ошибке.

    Returns:
        Словарь с данными ответа.

    Raises:
        ConnectionError: Если все попытки подключения не удались.
    """
    # Реализация функции
    pass

Стили оформления docstring

Существует несколько популярных стилей оформления docstring:

Пример в стиле NumPy:

def add(a, b):
    """Складывает два числа.

    Parameters
    ----------
    a : int или float
        Первое слагаемое.
    b : int или float
        Второе слагаемое.

    Returns
    -------
    int или float
        Сумма a и b.
    """
    return a + b

Пример в стиле Sphinx:

def multiply(a, b):
    """Умножает два числа.

    :param a: Первый множитель.
    :type a: int или float
    :param b: Второй множитель.
    :type b: int или float
    :returns: Произведение a и b.
    :rtype: int или float
    """
    return a * b

Docstring для классов и модулей

Docstring применяются не только к функциям. Они используются для документирования классов и целых модулей:

"""Модуль для работы с геометрическими фигурами.

Предоставляет классы Circle и Rectangle
для вычисления площади и периметра.
"""


class Circle:
    """Класс, представляющий круг.

    Attributes:
        radius: Радиус круга в условных единицах.
    """

    def __init__(self, radius):
        """Инициализирует круг с заданным радиусом.

        Args:
            radius: Радиус круга. Должен быть положительным числом.
        """
        self.radius = radius

    def area(self):
        """Вычисляет площадь круга."""
        return 3.14159 * self.radius ** 2

Разница между комментариями и docstring

Важно понимать ключевые различия:

Лучшие практики

Несколько рекомендаций по написанию комментариев и docstring:

• Пишите «зачем», а не «что». Код сам показывает, что он делает. Комментарий должен объяснять, почему выбрано именно такое решение
• Обновляйте комментарии. Устаревший комментарий хуже, чем его отсутствие
• Не комментируйте очевидное. x = x + 1 # увеличиваем x на 1 — бессмысленный комментарий
• Используйте docstring для публичного API. Каждая публичная функция, класс и модуль должны иметь docstring
• Выберите один стиль docstring и придерживайтесь его во всём проекте

# Плохо: комментарий дублирует код
counter = 0  # Устанавливаем счётчик в 0

# Хорошо: комментарий объясняет причину
counter = 0  # Сбрасываем счётчик перед повторной обработкой пакета

Частые ошибки

• Закомментированный код в production. Удаляйте ненужный код, а не комментируйте его — для истории есть Git
• Устаревшие комментарии. Комментарий, описывающий старую логику, вводит в заблуждение и создаёт баги
• Отсутствие docstring у публичных функций. Без документации пользователи вашего кода вынуждены читать исходники
• Использование docstring вместо комментариев. Тройные кавычки внутри тела функции (не в начале) — это просто строковый литерал, а не документация
• Слишком длинные инлайн-комментарии. Если комментарий длиннее самого кода, лучше вынести его на отдельную строку выше

Частозадаваемые вопросы

Можно ли использовать тройные кавычки для многострочных комментариев? Технически да, но это не настоящие комментарии. Python создаёт строковый объект, который затем удаляется сборщиком мусора. Для многострочных комментариев рекомендуется использовать несколько строк с #.

В чём разница между """ и ''' для docstring? Функциональной разницы нет. По соглашению PEP 257 рекомендуется использовать двойные кавычки """.

Нужно ли писать docstring для приватных методов? Это зависит от проекта. Для приватных методов со сложной логикой docstring полезен, но для простых внутренних методов он необязателен.

Как автоматически проверять наличие docstring? Используйте линтеры: pydocstyle проверяет соответствие PEP 257, а pylint предупреждает об отсутствии docstring у публичных объектов.

Влияют ли комментарии на производительность? Нет. Интерпретатор Python полностью игнорирует комментарии при компиляции байт-кода. Docstring сохраняются в памяти, но их влияние на производительность минимально.

Заключение

Комментарии и docstring — важные инструменты для создания читаемого и поддерживаемого кода на Python. Однострочные комментарии с # подходят для пояснений конкретных строк, многострочные блоки из # — для описания логики целых секций, а docstring — для документирования публичного API функций, классов и модулей. Для закрепления навыков работы с Python и написания профессионального кода рекомендуем курс Основы Python. В первых 3 модулях курса доступно бесплатное содержание, что позволяет освоить базовый синтаксис и понять структуру курса до покупки полного доступа.