Как писать docstrings

Докстринги (буквально «строки документации») — это встроенная в код документация (обычно после инициализации функции / класса и прочих объектов между двумя '''), которую могут читать люди и инструменты (help(), pydoc, автогенераторы). В этом лонгриде мы разберемся, где и как их писать.


Зачем нужны docstrings — и чем они отличаются от комментариев

🔘Комментарии (#) объясняют реализацию и помогают разработчикам; интерпретатор их игнорирует.
🔘Докстринги — это строковые литералы (обычно в """`), помещённые сразу после определения модуля / функции / класса / метода; они сохраняются в атрибуте .__doc__` и доступны в рантайме (через .__doc__, help() и инструментах вроде pydoc.

Докстринги описывают интерфейс (что делает код, какие аргументы и что возвращает), а комментарий — реализацию и все остальное.

Многострочные докстринги используются когда нужно подробнее описать параметры, поведение, побочные эффекты, примеры использования. По PEP 257 закрывающие кавычки обычно ставят на отдельной строке в многострочном docstring:

def get_book(publication_year, title):
    """
    Retrieve a Harry Potter book by its publication year and name.

    Parameters:
        publication_year (int): The year the book was published.
        title (str): The title of the book.

    Returns:
        str: A sentence describing the book and its publication year.
    """

Чтобы получить доступ к docstring в коде и терминале, вызываем:

🔘 obj.__doc__ — возвращает сырой docstring (часто краткий);
🔘 help(obj) — даёт структурированный вывод, полезный для модулей и классов;
🔘 python -m pydoc module — позволяет просматривать документацию из терминала и генерировать статичные страницы.


Что писать в docstring для модулей, функций и классов

Модуль:
🔘 Краткое описание назначения модуля.
🔘 При необходимости — описание экспортируемых переменных/классов/функций, примеры использования.

Функция / метод:
🔘 Краткое резюме (1–2 предложения).
🔘 Секция Parameters`/`Args: имена параметров, типы, краткое описание.
🔘 Секция Returns / Yields: что возвращается, тип.
🔘 Исключения: какие ошибки может выбросить функция (опционально, но полезно).
🔘 Пример использования или заметки о поведении (если нужно).

Класс:
🔘 Краткое описание назначения класса.
🔘 Описание атрибутов (публичных), краткая информация о методах (если интерфейс не очевиден).
🔘 Для сложных иерархий — примеры создания/использования. ([realpython.com][1])

#основы
@zen_of_python