Стандарты документации

Docstrings

Формат: Google-style для всех публичных классов, функций, методов.

def calculate_roi(investment: float, return_value: float, years: int = 1) -> float:
    """Calculate Return on Investment.

    Args:
        investment: Initial investment amount
        return_value: Total return after period
        years: Investment period in years (default: 1)

    Returns:
        ROI as a percentage (e.g., 150.0 for 150%)

    Raises:
        ValueError: If investment is zero or negative
    """
    if investment <= 0:
        raise ValueError("Investment must be positive")
    return ((return_value - investment) / investment) * 100

Когда писать docstrings

Всегда для публичных классов и методов
Для сложных приватных методов (более 10 строк)
Для модулей: краткое описание в начале файла

TODO и FIXME

# TODO(#TASK-42): Реализовать rate limiting
# FIXME(#BUG-7): Некорректный подсчёт при пустом списке

README.md

Каждая папка app/* должна содержать README.md с кратким описанием:

Назначение модуля
Ключевые классы/функции
Пример использования (если неочевидно)

ADR (Architecture Decision Records)

Каждое архитектурное решение фиксируется в docs/adr/NNN-title.md.

ADR нужен когда:

Выбирается технология (БД, фреймворк, провайдер)
Меняется архитектура (новый слой, новый паттерн)
Принимается решение с долгосрочными последствиями

ADR не нужен когда:

Обычный багфикс
Косметические изменения
Выбор имени переменной

CHANGELOG

CHANGELOG — это контракт с пользователем. Каждое изменение, влияющее на работу:

Для пользователей:

Новые функции
Изменения API
Исправления багов
Изменения зависимостей

Для разработчиков:

Рефакторинг (если влияет на API модуля)
Изменения конфигурации
Обновления БД

[ASK] Вопросы по документации

Генерировать документацию автоматически? (Sphinx, MkDocs — рекомендуется)
Нужна ли API документация для фронтенд-разработчиков? (да, OpenAPI доступен в /docs)
Какой формат для диаграмм? (Mermaid — рекомендуется, читается и человеком и ИИ)

3.0 KiB Raw Permalink Blame History