Что такое докстринги в Python

Что проверяют

Пишете ли вы документацию так, чтобы ею пользовались инструменты, а не только глаза соседа по команде. Заодно смотрят, понимаете ли, что докстринг это часть объекта в рантайме, а не комментарий.

Как отвечать

Докстринг это строковый литерал, стоящий первым выражением в модуле, классе, функции или методе. Он сохраняется в атрибуте __doc__ и доступен во время выполнения.

def add(a, b):
    """Сложить два числа.

    Args:
        a: первое слагаемое.
        b: второе слагаемое.

    Returns:
        Сумму аргументов.
    """
    return a + b

add.__doc__   # текст докстринга
help(add)     # он же в читаемом виде

Что стоит назвать дальше:

• соглашение об оформлении это PEP 257: тройные двойные кавычки, первая строка короткое описание одним предложением, дальше пустая строка и подробности;
• стили Google, NumPy и reST различаются только разметкой блоков про параметры и возвращаемое значение, а Sphinx и подобные генераторы собирают из них сайт документации;
• doctest исполняет примеры из докстринга как тесты, поэтому неверный пример превращается в красный прогон, а не в тихую ложь;
• инструменты редактора показывают докстринг во всплывающей подсказке, и это основной способ, которым его вообще читают.

Где спотыкаются

Путают докстринг с комментарием. Комментарий с # исчезает при компиляции, докстринг остаётся в объекте. Из этого следует практическое: строка, поставленная не первым выражением в теле, докстрингом уже не станет, а будет просто выражением без эффекта.

Второе: забывают про запуск с ключом -OO. В этом режиме докстринги выбрасываются из байткода, и код, который читает __doc__ по делу, например строит справку командной строки, в такой сборке ломается.

Третье: пересказывают сигнатуру вместо смысла. Строчка про то, что функция принимает два аргумента и возвращает сумму, не добавляет ничего к самому коду. Полезно другое: что функция делает с точки зрения вызывающего, какие исключения бросает, какие есть ограничения и побочные эффекты.