Всё о комментариях в языке программирования Python

Расширенные примеры комментариев

Пример 1: Docstring функции с подробным описанием

Следующий код демонстрирует функцию для вычисления факториала с полной документацией.

def factorial(n):
    """Вычисляет факториал целого неотрицательного числа.

    Параметры:
        n (int): Целое число, для которого вычисляется факториал.

    Возвращает:
        int: Факториал числа n.

    Вызывает:
        ValueError: Если n отрицательное.
    """
    if n < 0:
        raise ValueError('Факториал определён только для неотрицательных чисел')
    result = 1
    for i in range(2, n + 1):
        result *= i
    return result

help(factorial)

Help on function factorial in module __main__:

factorial(n)
    Вычисляет факториал целого неотрицательного числа.

    Параметры:
        n (int): Целое число, для которого вычисляется факториал.

    Возвращает:
        int: Факториал числа n.

    Вызывает:
        ValueError: Если n отрицательное.

Docstring позволяет автоматически сгенерировать справку, что упрощает использование функции другими разработчиками.

Пример 2: Комментирование сложного алгоритма (решето Эратосфена)

Пояснения позволяют разобраться в алгоритме без чтения каждой строки.

def sieve_of_eratosthenes(limit):
    """Возвращает список простых чисел до limit включительно."""
    # Создаём булевый массив, где True означает 'простое'
    is_prime = [True] * (limit + 1)
    # 0 и 1 не являются простыми
    is_prime[0] = is_prime[1] = False
    
    # Основной цикл: проходим от 2 до sqrt(limit)
    for p in range(2, int(limit**0.5) + 1):
        if is_prime[p]:
            # Вычёркиваем все кратные p, начиная с p*p
            for multiple in range(p*p, limit + 1, p):
                is_prime[multiple] = False
    
    # Собираем числа, оставшиеся простыми
    primes = [i for i, prime in enumerate(is_prime) if prime]
    return primes

print(sieve_of_eratosthenes(30))

[2, 3, 5, 7, 11, 13, 17, 19, 23, 29]

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

Пример 3: Отладка с помощью временных комментариев и меток TODO

В процессе разработки часто нужно отключить часть кода для тестирования. Хорошая практика - сопровождать такие изменения пометками.

def process_data(data):
    # TODO: реализовать проверку входных данных
    # if not data:
    #     return None
    
    # Временная заглушка: возвращаем сырые данные
    result = []
    for item in data:
        # item = item.strip()  # отключено для отладки
        result.append(item)
    return result

print(process_data([' a ', ' b ']))

[' a ', ' b ']

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

Пример 4: Inline-комментарии для пояснения выбора значений

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

MAX_RETRIES = 5  # Экспоненциальная задержка, 5 попыток достаточно
timeout = 30  # секунд, стандартный таймаут для HTTP

if retries > MAX_RETRIES:
    # Превышение лимита - вероятно, проблема с сетью
    raise ConnectionError('Не удалось установить соединение после нескольких попыток')

Такие комментарии не объясняют очевидное, а раскрывают мотивацию разработчика.