Разбивка кода на файлы — зачем и как

Вы написали 2000 строк в одном файле main.py. Поздравляем — вы только что создали себе головную боль на годы вперёд. В этом уроке разберёмся, почему один большой файл — это проблема, и как правильно организовать код по файлам.

😰 Представьте: 2000 строк в одном файле

Когда вы только начинаете программировать, всё кажется просто: создал файл main.py, написал туда весь код, запустил — работает. Отлично!

Но проект растёт. Появляются новые классы, функции, константы. Файл набухает: сначала 200 строк, потом 500, потом 1000, 2000... И вот здесь начинается настоящий кошмар.

Разберём конкретные боли, которые появляются с ростом файла:

💡 Главная мысль: разбивка кода — это про людей

Прежде чем идти дальше, запомните одну фундаментальную вещь:

Когда вы разбиваете проект на файлы — вы создаёте структуру для людей. Каждый файл — это отдельная «тема», отдельная «глава книги». Открыв файл models/user.py, любой разработчик мгновенно понимает: здесь живёт всё, что связано с пользователями.

Хорошо структурированный проект — это проявление уважения к другим людям (и к себе будущему). Это профессиональный навык, который отличает джуниора от мидла.

📁 До и после: структура проекта

Рассмотрим конкретный пример. Допустим, вы пишете простой интернет-магазин. Вот как выглядит типичный «монолитный» подход и правильная структура:

shop/
└── main.py          ← 2347 строк
    # строки 1-50: импорты
    # строки 51-200: класс User
    # строки 201-400: класс Product
    # строки 401-500: класс Cart
    # строки 501-700: класс Order
    # строки 701-900: функции работы с БД
    # строки 901-1100: функции отправки email
    # строки 1101-1400: расчёт доставки
    # строки 1401-1700: API-эндпоинты
    # строки 1701-2000: утилиты и хелперы
    # строки 2001-2347: тесты (!!!)

shop/
├── main.py          ← 30 строк (точка входа)
├── models/
│   ├── user.py      ← класс User
│   ├── product.py   ← класс Product
│   ├── cart.py      ← класс Cart
│   └── order.py     ← класс Order
├── services/
│   ├── database.py  ← работа с БД
│   ├── email.py     ← отправка писем
│   └── delivery.py  ← расчёт доставки
├── api/
│   └── endpoints.py ← API-эндпоинты
├── utils/
│   └── helpers.py   ← утилиты
└── tests/
    ├── test_user.py
    └── test_order.py

Видите разницу? Во втором случае, чтобы найти класс User, не нужно ничего искать — вы сразу открываете models/user.py. Хотите исправить расчёт доставки? services/delivery.py. Всё логично и предсказуемо.

🧩 Логическая группировка: каждый файл — одна тема

Как решить, что положить в какой файл? Задайте себе вопрос: «О чём этот код?»

Код, который отвечает на один и тот же вопрос, должен жить вместе. Несколько практических правил:

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

my_shop/
├── main.py               ← запускаем отсюда
├── models/
│   ├── __init__.py       ← пустой файл, делает папку пакетом Python
│   ├── product.py        ← класс Product
│   └── cart.py           ← класс Cart
└── utils/
    ├── __init__.py
    └── formatters.py     ← вспомогательные функции

Заметили файлы __init__.py? Это специальные пустые файлы, которые говорят Python: «эта папка — пакет, из неё можно импортировать». Без них Python не увидит папку как место, откуда можно делать import. Подробнее разберём в следующем уроке.

👀 Читаемость: проще найти нужный класс

Представьте: продакт-менеджер говорит вам: «Нужно добавить скидку к продукту». Где вы будете делать изменения?

Маленький файл с одной темой — это фокус внимания. Когда вы открываете models/product.py, вы точно знаете: всё, что здесь есть, связано с продуктом. Больше ничего. Это снижает когнитивную нагрузку и уменьшает риск ошибок.

👥 Командная разработка: разные люди — разные файлы

Программирование в реальных компаниях — это командная работа. Над одним проектом могут одновременно работать 5, 10, 50 человек. И здесь структура проекта становится критически важной.

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

♻️ Переиспользование: модуль в другом проекте

Ещё одно мощное преимущество хорошей структуры — возможность использовать код повторно.

Представьте: вы написали отличные утилиты для работы с датами — format_date(), days_between(), is_weekend(). Потом начинаете новый проект и понимаете, что те же функции нужны здесь тоже.

Именно так работают популярные библиотеки Python — requests, pandas, numpy. Каждая из них — это набор хорошо организованных файлов с чёткими темами. Вы просто пишете import requests и получаете доступ к сотням функций.

💻 Как это выглядит в коде

Давайте посмотрим на конкретный пример. Возьмём небольшой проект магазина и разобьём его по файлам. Всё, что нужно знать об import — разберём в следующем уроке, сейчас просто смотрите на структуру.

Файл models/product.py — только о продукте:

# models/product.py
# Этот файл знает только об одном: что такое Product

class Product:
    def __init__(self, name, price):
        self.name = name
        self.price = price

    def apply_discount(self, percent):
        """Применить скидку в процентах"""
        self.price = self.price * (1 - percent / 100)

    def __str__(self):
        return f"{self.name} — {self.price:.2f} руб."

Файл models/cart.py — только о корзине:

# models/cart.py
# Этот файл знает только об одном: что такое Cart

from models.product import Product  # берём Product из соседнего файла

class Cart:
    def __init__(self):
        self.items = []

    def add(self, product):
        self.items.append(product)

    def total(self):
        return sum(item.price for item in self.items)

    def __str__(self):
        lines = [str(item) for item in self.items]
        lines.append(f"Итого: {self.total():.2f} руб.")
        return "\n".join(lines)

Файл main.py — только точка входа, минимум кода:

# main.py
# Точка входа в программу — только запускает и соединяет части

from models.product import Product
from models.cart import Cart

# Создаём продукты
apple = Product("Яблоко", 50)
banana = Product("Банан", 30)
apple.apply_discount(10)   # скидка 10%

# Собираем корзину
cart = Cart()
cart.add(apple)
cart.add(banana)

print(cart)
# Яблоко — 45.00 руб.
# Банан — 30.00 руб.
# Итого: 75.00 руб.

📐 Принципы хорошей структуры проекта

Запомните несколько простых правил, которые помогут вам организовать код правильно:

✅ Итоги урока

• Монолитный файл на 2000 строк — это не проблема для компьютера, это проблема для людей: сложно искать, страшно менять, невозможно работать в команде без конфликтов.
• Разбивка по файлам — это про читаемость, сопровождение и командную работу. Компьютеру всё равно, люди скажут спасибо.
• Каждый файл — одна тема: user.py о пользователях, cart.py о корзине, email.py об отправке писем. Название файла = тема файла.
• Git и команда: разные люди работают с разными файлами — нет конфликтов при слиянии, каждый знает свою область.
• Переиспользование: изолированный модуль легко перенести в другой проект — просто скопируй файл и импортируй.
• main.py должен быть коротким — только точка входа, которая собирает компоненты вместе.

👉 В следующем уроке мы разберём механику Python-модулей: что такое import, как Python ищет файлы, зачем нужен __init__.py, и как правильно импортировать классы из других файлов. Теория закончилась — начнём писать код с нуля в нескольких файлах.