Andrey
d2d7c83575
Обновлены пути к библиотекам в Dockerfile для соответствия новой версии Python. Исправлены все тесты, теперь все проходят
107 lines
3.8 KiB
Markdown
107 lines
3.8 KiB
Markdown
---
|
||
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."""
|
||
...
|
||
```
|