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

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

1. Комментарии для генерации документации (Sphinx)

Sphinx распознаёт docstrings в формате reStructuredText. Пример модуля с документацией:

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

Содержит классы Circle и Rectangle.
"""

import math

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

    Атрибуты:
        radius (float): радиус круга
    """
    def __init__(self, radius):
        self.radius = radius

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

print(Circle.__doc__)
print(Circle.area.__doc__)

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

    Атрибуты:
        radius (float): радиус круга
    
Вычисляет площадь круга.

2. Использование комментариев для отладки с условной печатью

Часто временно включают отладочный вывод, закомментировав его или раскомментировав.

DEBUG = True  # Переключатель отладки

if DEBUG:
    # print("Отладочное сообщение 1")
    # print("Отладочное сообщение 2")
    pass

Удобнее использовать флаг с условным выполнением:

def debug(*args):
    if DEBUG:
        print(*args)

debug("Значение x:", x)

3. Комментарии в условных конструкциях и циклах

Пояснение сложной логики внутри циклов:

for i in range(100):
    # Пропускаем первые 10 итераций
    if i < 10:
        continue
    # Обработка только чётных чисел
    if i % 2 != 0:
        continue
    process(i)

4. Документирование функций с помощью аннотаций типов и docstring

Аннотации типов (Python 3.5+) не являются комментариями, но улучшают читаемость в сочетании с docstring:

def filter_positive(numbers: list[int]) -> list[int]:
    """
    Отбирает положительные числа из списка.

    Аргументы:
        numbers: список целых чисел.

    Возвращает:
        Список положительных чисел.
    """
    return [n for n in numbers if n > 0]

5. Комментарии для временного скрытия кода с помощью условной конструкции

Вместо комментирования строк можно использовать флаг:

ENABLE_FEATURE = False

if ENABLE_FEATURE:
    print("Новая функциональность")
else:
    print("Старая ветка")

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

6. Специальные комментарии для маркеров (TODO, FIXME) с поиском по проекту

# TODO: вынести в отдельный модуль
# FIXME: не учитывается часовой пояс
# HACK: временное решение до версии 2.0
def parse_date(date_str):
    return datetime.strptime(date_str, "%Y-%m-%d")

В PyCharm, VS Code и других IDE есть встроенный список TODO.

7. Комментарии внутри docstring с примерами использования (doctest)

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

    >>> add(2, 3)
    5
    >>> add(-1, 1)
    0
    """
    return a + b

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Запуск модуля выполнит тесты из docstring и выведет результаты.