Ответ.

История вопроса

В Python поощряется документирование кода через docstring еще с самых ранних версий. С появлением Python 3.5 (PEP 484) были добавлены аннотации типов (type hints) для повышения читаемости и улучшения поддержки анализаторов типов (например, mypy, pyright и др.). Таким образом, можно объединять документацию и типизацию непосредственно в определении функций и классов.

Проблема

Без аннотаций типов трудно быстро понять, с чем работает функция и чего от нее ожидать. Недостаток хороших docstring приводит к недопониманию интерфейса и ошибок использования. Если неправильно использовать type hints или docstrings, это мешает статическому анализу и ухудшает поддержку кода.

Решение

Использовать многострочные docstring для документирования назначения функции, параметров и результата, а также type hints для явного указания типов аргументов и возвращаемого значения.

Пример кода:

def add_numbers(a: int, b: int) -> int:
    """
    Складывает два целых числа и возвращает результат.

    :param a: Первое слагаемое, int
    :param b: Второе слагаемое, int
    :return: Сумма, int
    """
    return a + b

Ключевые особенности:

• Docstring хранится в doc и доступен для IDE, help(), автогенераторов документации
• Аннотации типов доступны через annotations; не влияют на выполнение кода, только для анализа
• Совмещённое применение облегчает масштабную поддержку и onboarding новых программистов

Вопросы с подвохом.

Могут ли аннотации типов повлиять на выполнение программы?

Нет. Аннотации типов (type hints) не проверяются интерпретатором Python во время исполнения и служат исключительно для анализаторов и IDE, а также для автогенерации документации. Они не приводят к ошибкам времени выполнения и всегда опциональны.

Можно ли использовать аннотации типов для ограничения значений параметра?

Нет. Указание типа, например, x: int не запрещает передачу значения другого типа на практике. Для этого можно использовать проверки времени выполнения (assert/isinstance), но не type hints — они не верифицируются автоматически.

Можно ли использовать комментарии # type: ... вместо аннотаций? Для чего это бывает нужно?

Да, это допускается, если нужна совместимость с Python 2 или со старыми кодовыми базами. Например:

def foo(x, y):     # type: (int, str) -> bool
    pass

Это понимают mypy и аналогичные инструменты наравне с современным синтаксисом, но в новых проектах лучше использовать стандартные аннотации.

Типовые ошибки и анти-паттерны

• Отсутствие docstring или пустой docstring у публичных функций и классов
• Неправильное указание типов — например, List вместо list или опечатки в типах (особенно со сложными коллекциями)
• Использование type hints без обновления документации и наоборот

Пример из жизни

Негативный кейс

В крупном проекте функции вообще не снабжены docstring и type hints — разработчик тратит много времени на изучение и отладку, часто ошибается с типами и назначением входных данных.

Плюсы:

• Быстрое написание кода в момент старта

Минусы:

• Большие трудности с сопровождением, onboarding новых сотрудников сильно затянут
• Ошибки сложно отлавливать, если типы параметров перепутаны

Позитивный кейс

Во всех публичных функциях есть развёрнутый docstring и корректные type hints, что позволяет IDE и анализаторам быстро находить ошибки типов и автоматически строить документацию для API.

Плюсы:

• Легко понимать и использовать чужой код
• Высокая устойчивость к ошибкам типов, простой рефакторинг

Минусы:

• Требует времени на написание и поддержание аннотаций и документации