Что такое docstring в Python?

Docstring (строка документации) в Python — это строковый литерал, который является первым оператором в модуле, функции, классе или методе. Он служит для описания назначения, аргументов, возвращаемых значений и общего использования этого программного элемента.

Почему это важно: Docstrings критически важны для создания самодокументируемого кода, значительно улучшают его читаемость и поддерживаемость. Они используются инструментами для автоматической генерации документации (например, Sphinx, Pydoc) и доступны во время выполнения через атрибут __doc__ или функцию help().

Пример:

def calculate_area(length: float, width: float) -> float:
    """
    Вычисляет площадь прямоугольника.

    Args:
        length (float): Длина прямоугольника.
        width (float): Ширина прямоугольника.

    Returns:
        float: Площадь прямоугольника (length * width).

    Raises:
        ValueError: Если длина или ширина отрицательны.
    """
    if length < 0 or width < 0:
        raise ValueError("Длина и ширина не могут быть отрицательными.")
    return length * width

print(calculate_area.__doc__) # Выведет docstring функции
help(calculate_area)          # Покажет форматированную документацию

Ключевые особенности и рекомендации:

• Формат: Обычно заключается в тройные двойные кавычки ("""Docstring"""). Допускаются и тройные одинарные ('''Docstring''').
• Многострочность: Может быть однострочной (для простых случаев) или многострочной (для подробного описания).
• Стандарты: Рекомендуется следовать общепринятым стандартам форматирования docstrings для единообразия и лучшей обработки инструментами. Наиболее популярные стили:
  • reStructuredText (reST): Используется Sphinx.
  • Google Style: Краткий и читаемый формат.
  • NumPy Style: Подходит для научных и числовых библиотек.
• Доступность: Доступны во время выполнения через object.__doc__ и функцию help(object).