92 lines
3.0 KiB
Markdown
92 lines
3.0 KiB
Markdown
# Стандарты документации
|
|
|
|
---
|
|
|
|
## 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 — рекомендуется, читается и человеком и ИИ)
|