На каждом ревью найдётся кто‑то, кто спросит «Зачем четыре файла, если это один пайплайн?»

А затем, давайте объясню!

Как это происходит

Очевидно, что никто не садится и не пишет processor.py на 900 строк намеренно.

Пайплайн трансфера артефактов стартует на 200 строк. Потом добавляется фильтрация, контроль целостности, обработка состояний, уведомления — и каждый раз кажется логичным добавить сюда же, рядом с похожим кодом. Через полгода открывая файл думаешь только о том, что лучше не трогать это без веской причины.

Причём архитектура при этом может быть вполне нормальной: файлы разделены по слоям, именование понятное. Просто один конкретный файл незаметно стал большим и это не джун‑ошибка — это нормальная энтропия под живые дедлайны.

Почему лимит вообще работает

Популярный аргумент звучит так: «большие файлы труднее читать, потому что рабочая память ограничена» — с отсылкой к Миллеру (1956) и Коуэну (2001). Это правда, но прямой экстраполяции нет: Миллер изучал запоминание случайных слогов, не чтение кода в IDE с навигацией по символам.

Реальная проблема — не в скролле. Она в неопределённости.

Когда открываешь permissions.py — область понятна из имени. Когда открываешь service.py на 800 строк с четырьмя разными ответственностями — сначала нужно восстановить карту файла в голове, и только потом трогать. Этот overhead не катастрофичен сам по себе, но он накапливается каждый раз, когда ты заходишь в файл.

Есть и эмпирика: Jay et al. (2009) проверили более 1,2 млн файлов из SourceForge и обнаружили линейную зависимость между LOC и цикломатической сложностью — устойчивую к языку и парадигме. Большой файл с высокой вероятностью сложный, независимо от аккуратности написания. Правда, Landman et al. (2016) эту корреляцию оспаривают — на Java и C результаты слабее. Данные неоднозначны. Но как первая метрика, которая дёшево считается и достаточно часто срабатывает — LOC работает.

Мои цифры — и почему они разные

Важный момент, который обычно упускают: я не использую одно число для всего кода. Разные типы файлов — разные лимиты.

Функция — 80 строк. Если не помещается в экран без скролла, скорее всего делает больше одного дела. 80 строк — это точка, где я останавливаюсь и спрашиваю: это действительно одна задача?

Handler / pipeline — 350 строк. Хендлер принимает событие, валидирует данные, передаёт дальше. Всё. Бизнес‑логики здесь нет. 350 строк — это около 10–12 хендлеров с валидацией. Больше — возможно, логика уже поехала не туда.

Processor / service — 450 строк. Здесь живёт реальная логика. 450 — точка, после которой мне становится тяжелее держать в голове внутренние зависимости класса без постоянного возврата наверх. Если перерастает — почти всегда это два смешанных контракта, а не просто «много кода».

Конкретные числа — из опыта, не из формул. Важнее сам принцип: для файлов с разной ответственностью лимиты разные и всегда есть исключения.

Пример 1 — FSM‑хендлер, который вырос органически

Задача: пошаговый мастер подачи заявки в боте (aiogram 3 + FSMContext). Девять шагов с ветками, отмена на любом этапе, inline‑клавиатуры на каждый переход.

До:

bot/
├── handlers/
│   ├── hr_request/
│   │   ├── __init__.py         # регистрация router
│   │   └── wizard.py           # ~800 строк за полгода выросло из 200:
│   │                           # добавлялись ветки флоу, keyboards рядом с хендлерами,
│   │                           # валидация там же - ведь "один флоу, незачем дробить"
│   └── admin.py
├── services/
│   └── ticket_service.py       # 310 строк
└── db/
    └── repository.py           # ~490 строк: один TicketRepository, CRUD + аналитические JOIN
                                # добавлялись методы по запросам

~800 строк в wizard.py — не хаос. Логика прослеживается, имена понятны. Проблема появляется, когда клавиатура на шаге 6 рендерит не то и нужно найти конкретный InlineKeyboardMarkup среди всего потока переходов. А правка клавиатуры рядом с логикой перехода — это риск задеть соседний код, который ты в этот момент вообще не читаешь.

Часто возникает вопрос: почему не два класса в одном файле? Потому что StepsHandler и WizardKeyboards меняются по разным причинам — первый при изменении бизнес‑логики, второй при изменениях UI.

В одном файле это смешивается в git diff: правка кнопки выглядит как правка флоу.

В разных файлах граница видна сразу — и в diff, и при импорте.

После:

bot/
├── handlers/
│   ├── hr_request/
│   │   ├── __init__.py
│   │   ├── states.py           # 25 строк  - StatesGroup
│   │   ├── steps.py            # 310 строк - только переходы
│   │   ├── keyboards.py        # 195 строк - клавиатуры по шагам
│   │   └── validators.py       # 120 строк - input валидация
│   └── admin.py
├── services/
│   └── ticket_service.py       # 310 строк
└── db/
    ├── ticket_repo.py          # 280 строк - CRUD + простые выборки
    └── ticket_queries.py       # 230 строк - агрегаты, JOIN, аналитика

Суммарный LOC немного вырос — за счёт импортов и init.py, но цель не в этом, цель — предсказуемая граница изменений: клавиатура шага 6 это keyboards.py на 195 строк, а не поиск по 800.

Репозиторий разбился по той же логике: CRUD‑методы и аналитические запросы меняются по разным поводам и теперьticket_queries.py трогаешь при новых отчётах, ticket_repo.py — при изменениях схемы. Разная частота, разные причины.

aiogram 3.x добавил Scene‑классы как осознанную альтернативу — весь флоу в одном изолированном классе. Валидный подход. Но если внутри сцены начинают жить генераторы клавиатур и валидационная логика — она вырастет точно так же.

Пример 2 — Maya‑процессор по типам ассетов

Начинали с mesh. Потом пришли rig, animation, fx — у каждого своя логика нормализации имён и валидации LOD.

До:

tools/
└── maya_asset_tool/
    ├── ui/
    │   └── main_window.py          # 290 строк
    ├── core/
    │   └── asset_processor.py      # ~680 строк: BaseProcessor + MeshProcessor + RigProcessor + AnimProcessor
    │                               # тут казалось логичным держать все процессоры вместе
    └── integrations/
        ├── perforce.py             # 170 строк
        └── maya_api.py             # 200 строк

Четыре хорошо написанных класса. Проблема в тестах: from core.asset_processor import RigProcessor тянет весь модуль — включая Maya‑зависимости MeshProcessor, которых в тестовой среде нет. Мокаешь то, что к тесту вообще не относится.

После:

tools/
└── maya_asset_tool/
    ├── ui/
    │   └── main_window.py          # 290 строк
    ├── core/
    │   ├── base_processor.py       # 110 строк
    │   ├── mesh_processor.py       # 185 строк
    │   ├── rig_processor.py        # 170 строк
    │   ├── anim_processor.py       # 150 строк
    │   └── validators.py           # 125 строк
    └── integrations/
        ├── perforce.py             # 170 строк
        └── maya_api.py             # 200 строк

from core.rig_processor import RigProcessor — только то, что нужно.

Пришёл VFX — создаёшь vfx_processor.py, остальные не трогаешь.

Граница изменений стала явной.

Когда большой файл нормален

Тексты и шаблоны. Файл на 900 строк из констант или строк, сгруппированных по классам, читается совершенно иначе. Нет зависимостей между блоками, нет сайд‑эффектов. Открыл, нашёл нужный класс, поправил.

Репозиторий на 500+ строк — нормально, если все методы независимы, каждый не длиннее ~50 строк, никакой бизнес‑логики. Например, get_by_id() ничего не знает про get_with_analytics() (у сервисного слоя зависимостей между методами больше, поэтому и порог ниже).

Scene в aiogram 3x — осознанное архитектурное решение фреймворка, а не исключение из правил.

Как это контролировать

Лимиты работают только если их не нужно помнить. Мы с коллегой ввели простую проверку в CI: скрипт считает непустые строки в файлах по суффиксу имени и возвращает варнинги, если файл перевалил за лимит своего типа. Не как строгий запрет, а чтобы сделать превышение видимым.

Если файл растёт — это должно быть осознанным решением с явным исключением, а не случайным дрейфом, который замечаешь через три месяца.

Инструмент, которым пользуются каждый день, не прощает «знаю где баг, но не знаю что зацеплю». Лимиты на размер файлов — один из способов держать эту уверенность на протяжении нескольких лет жизни проекта.

Не универсальный рецепт. Просто то, что работает у меня уже несколько лет.

А у Вас есть формальные ограничения в команде, или держитесь на договорённостях?