Документирование проекта

Документация — это критический компонент любого серьёзного проекта. Хорошая документация экономит время, предотвращает ошибки и облегчает onboarding новых разработчиков.

Виды документации, которые я писал

1. README.md (в корне проекта)

Первое, что видит разработчик:

# Project Name

## Описание
Краткое описание что это и зачем нужно.

## Требования
- Python 3.9+
- PostgreSQL 12+
- Redis 6.0+

## Установка
\`\`\`bash
git clone ...
cd project
pip install -r requirements.txt
python manage.py migrate
\`\`\`

## Запуск
\`\`\`bash
python manage.py runserver
\`\`\`

## Структура проекта
\`\`\`
project/
├── app/
│   ├── models.py
│   ├── views.py
│   ├── tests.py
├── requirements.txt
├── manage.py
\`\`\`

## API документация
Смотрите docs/API.md

## Контриьютинг
Смотрите CONTRIBUTING.md
\`\`\`

**2. Docstrings в коде**

```python

def calculate_discount(price: float, discount_percent: float) -> float: """ Рассчитывает цену с учетом скидки.

Args:
    price: Исходная цена в рублях
    discount_percent: Размер скидки в процентах (0-100)

Returns:
    Цена после скидки

Raises:
    ValueError: Если discount_percent < 0 или > 100

Example:
    >>> calculate_discount(1000, 10)
    900.0
"""
if not 0 <= discount_percent <= 100:
    raise ValueError("Скидка должна быть от 0 до 100%")
return price * (1 - discount_percent / 100)

3. API документация (Swagger/OpenAPI)

from fastapi import FastAPI from pydantic import BaseModel

app = FastAPI(title="My API", version="1.0.0")

class User(BaseModel): """Модель пользователя""" id: int name: str email: str

@app.get("/users/{user_id}", response_model=User)

async def get_user(user_id: int): """ Получить пользователя по ID.

- **user_id**: ID пользователя

Returns: Объект пользователя
"""
return {"id": user_id, "name": "John", "email": "john@example.com"}

Swagger доступен на /docs

ReDoc доступен на /redoc

Django + DRF:

from rest_framework import viewsets from rest_framework.decorators import action

class UserViewSet(viewsets.ModelViewSet): """ API для управления пользователями.

list: Получить список пользователей
create: Создать нового пользователя
retrieve: Получить пользователя по ID
update: Обновить пользователя
destroy: Удалить пользователя
"""
queryset = User.objects.all()
serializer_class = UserSerializer

@action(detail=True, methods=['post'])
def send_email(self, request, pk=None):
    """Отправить email пользователю"""
    user = self.get_object()
    # ...

4. Architecture docs (docs/ARCHITECTURE.md)

Архитектура проекта

## Layered Architecture

\`\`\`
┌─────────────────────────────────┐
│      Presentation Layer         │
│   (FastAPI, REST endpoints)     │
├─────────────────────────────────┤
│     Application Layer           │
│    (Use Cases, Services)        │
├─────────────────────────────────┤
│       Domain Layer              │
│   (Models, Business Logic)      │
├─────────────────────────────────┤
│    Infrastructure Layer         │
│   (Database, Cache, API calls)  │
└─────────────────────────────────┘
\`\`\`

## Зависимости

Зависимости всегда направлены внутрь:
- Presentation → Application → Domain
- Infrastructure → Application → Domain

Нарушение слоев недопустимо.

## Примеры

### Domain Layer
- User (entity)
- UserRepository (interface)

### Application Layer
- CreateUserUseCase
- GetUserUseCase

### Infrastructure Layer
- PostgresUserRepository (implementation)

### Presentation Layer
- UserRouter (FastAPI)
- UserResponse (Pydantic model)
\`\`\`

**5. SETUP.md для разработчиков**

```markdown
# Setup для разработки

## Установка зависимостей

\`\`\`bash
# Создать виртуальное окружение
python -m venv venv
source venv/bin/activate  # на Windows: venv\Scripts\activate

# Установить зависимости
pip install -r requirements-dev.txt

# Установить pre-commit hooks
pre-commit install
\`\`\`

## Миграции БД

\`\`\`bash
# Применить миграции
alembic upgrade head

# Создать новую миграцию
alembic revision --autogenerate -m "Add column"

# Откатить последнюю миграцию
alembic downgrade -1
\`\`\`

## Запуск тестов

\`\`\`bash
# Все тесты
pytest

# С покрытием
pytest --cov=app

# Watch mode
ptw
\`\`\`

## Запуск проекта

\`\`\`bash
# Development сервер с автозагрузкой
uvicorn app.main:app --reload

# Production
gunicorn app.main:app -w 4 -b 0.0.0.0:8000
\`\`\`
\`\`\`

**6. Testing documentation**

```markdown

Тестирование

## Структура тестов

\`\`\`
tests/
├── unit/
│   ├── domain/
│   ├── application/
│   └── infrastructure/
├── integration/
└── e2e/
\`\`\`

## Запуск

\`\`\`bash
pytest tests/unit  # Unit тесты
pytest tests/integration  # Integration
pytest  # All
\`\`\`

## Примеры

### Unit Test

\`\`\`python

def test_calculate_discount(): assert calculate_discount(1000, 10) == 900 assert calculate_discount(100, 0) == 100

with pytest.raises(ValueError):
    calculate_discount(100, 150)

\`\`\`

### Integration Test

\`\`\`python
@pytest.mark.asyncio

async def test_create_user_endpoint(client): response = await client.post("/users", json={ "name": "John", "email": "john@example.com" }) assert response.status_code == 201 assert response.json()["id"] is not None

\`\`\`
\`\`\`

**7. Deployment docs (DEPLOY.md)**

```markdown
# Развертывание

## Environment variables

Создайте .env файл:

\`\`\`
DATABASE_URL=postgresql://user:password@localhost/dbname
SECRET_KEY=your-secret-key
DEBUG=False
\`\`\`

## Docker

\`\`\`bash
# Build
docker build -t myapp .

# Run
docker run -p 8000:8000 myapp
\`\`\`

## Production (Gunicorn + Nginx)

\`\`\`bash
# Установить Gunicorn
pip install gunicorn

# Запустить
gunicorn app.main:app -w 4 -b 0.0.0.0:8000 &

# Nginx конфиг...
\`\`\`
\`\`\`

### Инструменты для документации

**1. Sphinx + ReadTheDocs** (для больших проектов)

```bash
sphinx-quickstart docs
make html  # Build HTML docs

2. MkDocs (простой и красивый)

pip install mkdocs
mkdocs new project
mkdocs serve  # localhost:8000

3. API документация

• Swagger UI (FastAPI встроенный, DRF с drf-spectacular)
• ReDoc (красивая альтернатива Swagger)
• Postman (для тестирования API)

4. Диаграммы

• Mermaid (прямо в markdown)
• PlantUML (для UML диаграмм)
• draw.io (простые диаграммы)

Что я документирую

✅ Обязательно:

• Как установить и запустить проект
• API endpoints с примерами запросов
• Основные компоненты архитектуры
• Как разворачивать в production

✅ Важно:

• Docstrings для основных функций
• Примеры использования
• Решение распространённых проблем
• Процесс контрибьютинга

⚠️ Когда есть время:

• Детальное описание алгоритмов
• Performance туningи и optimization
• История решений (Architectural Decision Records)

Практические советы

1. Документация вместе с кодом — не отдельно
2. Примеры должны работать — проверяйте копирование из примеров
3. Актуальность — обновляйте при изменении кода
4. Краткость — лучше короче, но ясно
5. Иерархия — от простого к сложному

Выводы

Хорошая документация:

• Экономит время — разработчики быстрее разбираются
• Снижает ошибки — все знают как работает
• Облегчает maintenance — легче поддерживать код
• Показывает профессионализм — качество кода и документации