---
description: "Стиль кода, соглашения по именованию и форматированию"
alwaysApply: true
---

# Стиль кода и соглашения

## Именование

### Классы
- **PascalCase**: `UserRepository`, `AdminService`, `BaseDependencyFactory`
- Имена классов должны быть существительными

### Функции и методы
- **snake_case**: `get_user_info()`, `handle_message()`, `create_tables()`
- Имена функций должны быть глаголами или начинаться с глагола

### Переменные
- **snake_case**: `user_id`, `bot_db`, `settings`, `message_text`
- Константы в **UPPER_SNAKE_CASE**: `FSM_STATES`, `ERROR_MESSAGES`

### Модули и пакеты
- **snake_case**: `admin_handlers.py`, `user_repository.py`
- Имена модулей должны быть короткими и понятными

## Импорты

Структура импортов (в порядке приоритета):

```python
# 1. Standard library imports
import os
import asyncio
from typing import Optional, List

# 2. Third-party imports
from aiogram import Router, types
from aiogram.filters import Command

# 3. Local imports - модули проекта
from database.async_db import AsyncBotDB
from helper_bot.handlers.admin.services import AdminService

# 4. Local imports - utilities
from logs.custom_logger import logger

# 5. Local imports - metrics (если используются)
from helper_bot.utils.metrics import track_time, track_errors
```

## Type Hints

- Всегда используйте type hints для параметров функций и возвращаемых значений
- Используйте `Optional[T]` для значений, которые могут быть `None`
- Используйте `List[T]`, `Dict[K, V]` для коллекций
- Используйте `Annotated` для dependency injection в aiogram

Пример:
```python
async def get_user_info(self, user_id: int) -> Optional[Dict[str, Any]]:
    """Получение информации о пользователе."""
    ...
```

## Документация

### Docstrings
- Используйте docstrings для всех классов и публичных методов
- Формат: краткое описание в одну строку или многострочный с подробностями

```python
async def add_user(self, user: User) -> None:
    """Добавление нового пользователя с защитой от дублирования."""
    ...
```

### Комментарии
- Комментарии на русском языке (как и весь код)
- Используйте комментарии для объяснения "почему", а не "что"
- Разделители секций: `# ============================================================================`

## Форматирование

- Используйте 4 пробела для отступов (не табы)
- Максимальная длина строки: 100-120 символов (гибко)
- Пустые строки между логическими блоками
- Пустая строка перед `return` в конце функции (если функция не короткая)

## Структура файлов handlers

```python
# 1. Импорты (по категориям)
# 2. Создание роутера
router = Router()

# 3. Регистрация middleware (если нужно)
router.message.middleware(SomeMiddleware())

# 4. Handlers с декораторами
@router.message(...)
@track_time("handler_name", "module_name")
@track_errors("module_name", "handler_name")
async def handler_function(...):
    """Описание handler."""
    ...
```