telegram-helper-bot/.cursor/rules/code-style.md

description, alwaysApply

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
• Имена модулей должны быть короткими и понятными

Импорты

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

# 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

Пример:

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

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

Docstrings

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

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

Комментарии

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

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

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

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

# 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."""
    ...