Зачем нужна документация к коду и к API, и что в неё стоит включать в первую очередь?

Короткий ответ

Документация помогает другим разработчикам (и вам через полгода) быстро понять назначение, входные данные и ограничения кода или эндпоинта без чтения всей реализации.

Как это работает подробнее

Для функций и модулей документация обычно описывает назначение, параметры, возвращаемое значение и возможные исключения. Для API — это формат запроса и ответа, коды ошибок, обязательность полей и примеры вызовов. Такая документация выступает контрактом между частями системы или между командами, снижая зависимость от того, что автор кода помнит детали и доступен для вопросов.

Пример кода

example.pyКопировать

def charge_card(amount: float, currency: str) -> str:
    """Списывает сумму с привязанной карты пользователя.
    Args:
        amount: сумма списания, должна быть > 0.
        currency: код валюты ISO 4217, например "RUB".
    Returns:
        Идентификатор транзакции в платёжном шлюзе.
    Raises:
        PaymentDeclinedError: если платёж отклонён банком.
    """
    return "transaction-id"

Что использовать на практике

• Практика. Докстроки и комментарии стоит писать там, где поведение не очевидно из названия и типов, а не дублировать код словами. Для REST API удобно поддерживать OpenAPI/Swagger-спецификацию — она же может использоваться для автогенерации клиентов, валидации запросов и построения интерактивной песочницы для других команд.

Подводные камни

• Риски. Частая ошибка — документировать «что делает код» дословно по строкам вместо «зачем» и «какие есть ограничения» (например, не описывают, что функция не потокобезопасна или что поле опционально только при определённом условии). Другая ошибка — не обновлять документацию при изменении кода, из-за чего она начинает врать и доверие к ней падает, а разработчики возвращаются к чтению исходников. Также часто забывают документировать коды ошибок и граничные случаи, хотя именно они чаще всего вызывают вопросы у интеграторов.