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

---

## Docstrings

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

```python
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

```python
# 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 — рекомендуется, читается и человеком и ИИ)