Молодые разработчики, а иногда и опытные, стремясь сделать код «идеальным», часто уходят в оверинжиниринг и создают трудночитаемые конструкции. В итоге на реализацию уходит больше времени, а поддержка превращается в хард-квест с поиском ответов.    

Если и у вас есть желание написать какую-нибудь сложную абстракцию «на будущее» или применить новый паттерн просто потому, что вы его выучили — остановитесь на секунду.

Совместно с Python-разработчиками Далее мы собрали все, что поможет писать код, который не стыдно показать тимлиду и легко развивать дальше:

• Базовые принципы чистого кода

• Инструменты, которые помогают писать чисто и понятно

• Сигналы, что «порядок» превращается в оверинжиниринг

• Чек-лист, как писать без перегрузки

Базовые принципы чистого кода

Основа разработки — писать код не для компилятора, а для людей. Для коллег, которые будут его читать, править и расширять проект с нами и после нас. И есть минимум четыре критерия, которые делают написанное нами простым и понятным.

Легко определяемые названия переменных, функций, классов

Это основа основ. Имя должно сразу и однозначно говорить о цели сущности. Правило простое: если вам приходится лезть в реализацию, чтобы понять, что делает функция или что хранит переменная — имя выбрано плохо. Для сравнения:

#Что такое 'd'? Что делает 'proc'?
def proc(d):
    for i in d:
        if i.a: 
            ...

#Сразу ясны и данные, и цель функции.
def validate_orders(orders: list[Order]) -> list[Order]:
    for order in orders:
        if order.is_active: # <- Булевый флаг с префиксом is_
            # ... логика проверки

Маленький, но очень полезный прием — использовать префиксы is_ и has_ для булевых значений. Это сразу дает понять, что мы работаем с флагом.

 #Что такое 'active'? Число? Строка? Объект?
if user.active:
    ...

#Здесь ясно, что это True/False. 
if user.is_active:
    ...

Не экономьте на названиях: лучше calculate_monthly_revenue(), чем calc_mrev() — код будет читаться как книга.

Читаемость «по диагонали»

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

— понятных имен (см. пункт 1);
— отсутствия глубокой вложенности условий и циклов;
— простых функций, которые делают одну вещь и делают ее хорошо.

Вот наглядный пример, где глубокая вложенность условий — первый признак того, что код нужно упростить, и стоит применить классическое решение — ранний выход (guard clauses):

#Плохо: три уровня вложенности, нужно «разматывать» логику. 
def process_order(order):

    if order is not None:

        if order.user is not None:

            if order.user.is_active:

                for item in order.items:

                    if item.in_stock:

                        ship(item)

#Хорошо: ранние выходы, логика читается сверху вниз. 
def process_order(order):

    if not order or not order.user or not order.user.is_active:

        return

    for item in order.items:

        if item.in_stock:

            ship(item)

Такой код не требует декодирования — его логика всем очевидна.

Минимум комментариев — они не нужны, если все видно по коду

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

Хороший код должен быть самоочевидным. Стремитесь к тому, чтобы пояснений было мало и они раскрывали только неочевидные решения, принятые исходя из бизнес-логики или технических ограничений — того, чего из самого кода не видно.

Примеры полезных комментариев:

#НДС для B2B-клиентов не начисляем: договор предусматривает его уплату на стороне клиента
if user.is_business:

    total = price * quantity

else:

    total = price * quantity * VAT_RATE

#sleep нужен для обхода rate limit стороннего API (макс. 10 запросов/сек)
time.sleep(0.1)

send_request(payload)

Лаконичные конструкции

Желание блеснуть знанием языка ведет к неоправданным решениям. В ход идут сложные однострочники, моржовые операторы (:=) в неочевидных местах или избыточные конструкции.

Но часто лучше разбить логику на несколько шагов, чем втиснуть ее в одну «умную» строку.

#Сложно: нужно разбирать условие. 
if (user := session.get_current_user()) and user.is_admin:
    grant_access(user)

#Проще и лаконичнее: читается линейно, без усилий. 
user = session.get_current_user()
if user and user.is_admin:
    grant_access(user)

Лаконичность — это не про количество строк, а про ясность каждой из них. Возьмем другой пример — функцию, которая ищет товар (item) по одному из двух возможных ключей: code1 или code2.

Усложненный код:

async def find_item(code, db):

    i1_q = await db.execute(select(Item).where(Item.code1 == code))

    i2_q = await db.execute(select(Item).where(Item.code2 == code))

    item = ""
    item_descr = ""

    if item_object := i1_q.scalars().first():

        item = item_object.name

        item_descr = item_object.descr

    if item_object := i2_q.scalars().first():

        item = item_object.name

        item_descr = item_object.descr

    return item, item_descr

Ключевые ошибки данного кода:

• недостаточно явный флоу функции, что затрудняет ее чтение.

• неочевидное наименование самой функции и два вызова к базе данных без необходимости.

• некорректны названия переменных: вместо возвращения объекта item — возвращение кортежа строк.

Пример той же функции, но чище:

async def get_item_by_code1_or_code2(code: int) -> Item | None:

Используем общую абстракцию для работы с БД, а не пишем запросы вручную в каждой функции:

repository = ItemRepository()

    item = await repository.filter(code1=code)

    if item:

        return item

    item = await repository.filter(code2=code)

    if item:

        return item

    return None

В данном случае функция выполняет то же самое, но здесь понятный флоу, который схватывается, не задумываясь. Использована уместная абстракция для работы с базой данных и своевременные обращения к ней. Есть ясное название функции и типизация.

Код выглядит намного понятнее, чем в первом примере. В будущем мы потратим намного меньше времени на понимание того, что происходит внутри.

Инструменты, которые помогают писать чисто и понятно

Создание понятного кода — это не только вопрос личной дисциплины. Это системный подход, который требует использования правильных инструментов и выработки общих правил. 

Стайл-гайды мастодонтов

Если вы все еще откладываете знакомство с PEP8 и Google Python Style Guide, то рекомендем сделать это в самое ближайшее время. Эти стандарты написаны опытными разработчиками и содержат продуманные рабочие решения. Они — отправная точка, которая избавляет команды от бесконечных споров о том, как оформлять код. 

Но сторонние стайл-гайды не являются абсолютной истиной для каждого проекта. Ключ в том, чтобы использовать их как прочную основу, но быть готовыми адаптировать правила под конкретные требования.

Внутренние договоренности

Внутреннее руководство по стилистике кода значительно упростит понимание синтаксиса для всех участников проекта. Это касается не только именования переменных и функций, но и более высокоуровневых вещей: организации модулей, соглашений по именованию сервисов, структуры проектов. 

Такие договоренности позволят каждому в команде прочесть код и облегчат дальнейшую поддержку.

Линтеры

Инструменты, как Flake8 и Pylint, выполняют роль автоматических ревьюеров. Они не только проверяют соответствие стилю, но и выявляют потенциальные ошибки и сложные участки кода. Но линтеры стоит использовать рационально: они часто выдают много предупреждений, и не все из них достойны внимания. 

Pylint-вывод для кода:

• W0611: Unused import 'json' (unused‑import) ← полезно: мусор в импортах

• E1101: Module 'os' has no 'makedirss' member ← полезно: опечатка в имени функции

• C0121: Comparison to True should be 'if cond is True' ← полезно: семантическая проблема

• C0103: Variable name 'i' doesn't conform to snake_case ← шум: в циклах однобуквенные имена — норма

• R0914: Too many local variables (16/15) ← контекстно: иногда оправдано

• C0301: Line too long (102/100) ← настраивайте под команду, не под инструмент

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

Код в первую очередь должен быть понятен людям, а не машинам.

Форматеры — must have для любого проекта

Если линтеры советуют, то форматеры делают. Инструменты вроде Black и Isort автоматически приводят весь код к единому стилю. Black беспощадно форматирует все: отступы, переносы строк, расстановку пробелов и запятых. Isort приводит в порядок импорты. Главное их преимущество — они упрощают код-ревью.

Пример кода до и после форматтера Black:

#До — пробелы «как попало», лишние скобки, нет отступа
if(user.is_active==True):

print("OK")

#После Black — правильные пробелы, убраны лишние скобки, отступы на месте.
if(user.is_active==True):

print("OK")

Обратите внимание: Black занимается только форматированием — пробелами, отступами, скобками. Семантические улучшения вроде замены == True на просто is_active — это уже задача линтера (Pylint выдаст предупреждение C0121: singleton-comparison) или разработчика на код-ревью.

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

Сигналы, что «порядок» превращается в оверинжиниринг

Парадоксально, но, даже зная и используя все вышеперечисленное, можно уйти в оверинжиниринг. Часто именно в погоне за «идеальностью» разработчики начинают усложнять то, что можно было сделать проще. Разделяют приложение на десятки ненужных слоев, создают абстракции на каждый «чих» и размывают бизнес-логику. 

Сложные архитектурные решения оправданы только тогда, когда есть точная уверенность в масштабе и требованиях проекта, подтвержденная бизнес-анализом.

Ниже — конкретные признаки, по которым можно понять, что вы идете в направлении оверинжиниринга.

Ранняя оптимизация

Не стоит оптимизировать код без необходимости — это часто ухудшает его понятность и простоту. Сначала нужно сделать работающее решение, а потом оптимизировать только те места, которые в этом действительно нуждаются.

Классический пример — преждевременное кеширование.

Плохо — добавляем кеш «на всякий случай», до измерений:

from functools import lru_cache

@lru_cache(maxsize=128)

def get_user_role(user_id: int) -> str:

    return db.query(UserRole).filter_by(user_id=user_id).first().name

Теперь кеш нужно инвалидировать при изменении роли пользователя. Сложность выросла, а реальная проблема с производительностью могла и вовсе не существовать.

Хорошо — сначала простое решение, потом — оптимизация по данным профилировщика:

def get_user_role(user_id: int) -> str:

    return db.query(UserRole).filter_by(user_id=user_id).first().name

Как говорил Дональд Кнут: «Преждевременная оптимизация — корень всех зол». Сначала заставьте код работать правильно, потом — при необходимости — быстро.

Слепое следование принципам

Шаблоны проектирования, SOLID, DDD — это ориентиры, а не обязательства. Они не всегда подходят для частных задач. Нужно мыслить практично и логически. 

Приведем утрированный, но вполне реальный пример. Разработчику нужно поприветствовать пользователя — формально или нет. Вместо функции из двух строк появляется вот это…

Плохо — Factory + Strategy + ABC ради одного f-string:

from abc import ABC, abstractmethod

class AbstractGreetingFormatter(ABC):

    @abstractmethod

    def format(self, name: str) -> str: ...

class FormalGreetingFormatter(AbstractGreetingFormatter):

    def format(self, name: str) -> str:

        return f"Уважаемый {name},"

class InformalGreetingFormatter(AbstractGreetingFormatter):

    def format(self, name: str) -> str:

        return f"Привет, {name}!"

class GreetingFormatterFactory:

    @staticmethod

    def create(style: str) -> AbstractGreetingFormatter:

        if style == "formal":

            return FormalGreetingFormatter()

        return InformalGreetingFormatter()

class GreetingService:

    def __init__(self, formatter: AbstractGreetingFormatter):

        self.formatter = formatter

    def greet(self, name: str) -> str:

        return self.formatter.format(name)

formatter = GreetingFormatterFactory.create("informal")

service = GreetingService(formatter)

print(service.greet("Иван"))  # "Привет, Иван!"

Четыре класса, фабрика, абстрактный базовый класс — и все это ради f"Привет, {name}!". Ниже — как выглядит то же самое без оверинжиниринга.

Хорошо — функция на две строки:

def greet(name: str, formal: bool = False) -> str:

    return f"Уважаемый {name}," if formal else f"Привет, {name}!"

print(greet("Иван"))  # "Привет, Иван!"

Паттерны Factory и Strategy уместны, когда реализаций действительно несколько и они могут меняться в рантайме. Но если у вас два фиксированных варианта поведения — это просто if.

Слишком много слоев приложения

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

Задача: создать заказ. Роутер принял запрос и передал управление в сервисный слой. Дальше начинается интересное.

Плохо — внутри сервисного слоя четыре класса, логика — только в последнем:

# order_service.py

class OrderService:

    async def create_order(self, user_id: int, items: list[OrderItem]) -> Order:

        use_case = CreateOrderUseCase(repository=OrderRepository())

        return await use_case.execute(user_id, items)

# create_order_use_case.py

class CreateOrderUseCase:

    def __init__(self, repository: OrderRepository):

        self.repository = repository

    async def execute(self, user_id: int, items: list[OrderItem]) -> Order:

        validator = OrderValidator()

        validator.validate(items)

        manager = OrderManager(self.repository)

        return await manager.process(user_id, items)

# order_validator.py

class OrderValidator:

    def validate(self, items: list[OrderItem]) -> None:

        if not items:

            raise ValueError("Order must have items")

# order_manager.py

class OrderManager:

    def __init__(self, repository: OrderRepository):

        self.repository = repository

    async def process(self, user_id: int, items: list[OrderItem]) -> Order:

        total = sum(item.price * item.quantity for item in items)

        order = Order(user_id=user_id, items=items, total=total)

        return await self.repository.save(order)

Четыре класса, четыре файла — OrderService, CreateOrderUseCase, OrderValidator, OrderManager. Чтобы понять, что делает create_order, нужно открыть их все. При этом вся реальная работа — две строки — сосредоточена только в OrderManager. Остальное — пустые оболочки.

Хорошо — один сервис, тот же результат:

class OrderService:

    def __init__(self, repository: OrderRepository):

        self.repository = repository

    async def create_order(self, user_id: int, items: list[OrderItem]) -> Order:

        if not items:

            raise ValueError("Order must have items")

        total = sum(item.price * item.quantity for item in items)

        order = Order(user_id=user_id, items=items, total=total)

        return await self.repository.save(order)

Слоев по-прежнему три: роутер, сервис, репозиторий. Договоренности не нарушены. Просто внутри сервиса нет лишних оберток — логика живет там, где ей место.

Реализация «на будущее»

Нет смысла закладывать универсальность и расширения, которые сейчас бизнесу не нужны. Мы пишем код не ради того, чтобы писать код, а для того, чтобы решать частные задачи. Если бизнесу нужен интернет-магазин — нужно сделать просто интернет-магазин, а не строить архитектуру как для Amazon.

В экстремальном программировании этот принцип давно сформулирован как YAGNI — You Aren't Gonna Need It («Вам это не понадобится»). Каждый раз, когда хочется написать «а вдруг пригодится» — остановитесь и спросите себя: есть ли сейчас реальная задача, которую это решает? Если нет — не пишите.

Яркий пример — выбор микросервисов для маленького проекта. Представьте локальный магазин на 300 пользователей. Логичное решение — взять Django и сделать все в монолите: админку, аутентификацию, логику магазина. Структура проекта простая, запуск — одна команда:

shop/

├── manage.py

├── config/

│   ├── settings.py

│   └── urls.py

├── users/

│   ├── models.py

│   ├── views.py

│   └── urls.py

├── products/

│   ├── models.py

│   ├── views.py

│   └── urls.py

└── orders/

    ├── models.py

    ├── views.py

    └── urls.py

# Запустить все приложение локально:

python manage.py runserver

Оверинжиниринг здесь — это когда тот же магазин решают разбить на микросервисы: «вдруг вырастем». В итоге docker-compose для локальной разработки выглядит вот так:

# docker-compose.yml для «маленького» магазина на 300 пользователей

services:

  api-gateway:

    build: ./api-gateway

    ports: ["8000:8000"]

  user-service:

    build: ./user-service

    depends_on: [postgres-users, rabbitmq]

  product-service:

    build: ./product-service

    depends_on: [postgres-products]

  order-service:

    build: ./order-service

    depends_on: [postgres-orders, rabbitmq, redis]

  review-service:

    build: ./review-service

    depends_on: [postgres-reviews]

  postgres-users:

    image: postgres:15

  postgres-products:

    image: postgres:15

  postgres-orders:

    image: postgres:15

  postgres-reviews:

    image: postgres:15

  rabbitmq:

    image: rabbitmq:3-management

  redis:

    image: redis:7

Чтобы запустить локально — docker-compose up с 11 контейнерами. Чтобы задеплоить — отдельный CI/CD-пайплайн для каждого сервиса. Чтобы отладить баг, затрагивающий заказы и пользователей, — открыть логи двух сервисов, разобраться с асинхронными сообщениями через RabbitMQ и проверить сетевое взаимодействие через API Gateway. Всё это — для магазина, у которого и запросов-то пока нет.

Лучше начать с простого и потом по необходимости разделять, чем делать тройную работу с самого начала, которая может не понадобиться. 

Чек-лист, как писать без перегрузки 

Оверинжиниринг — это код, который решает проблему слишком сложным путем, не оправданным требованиями проекта. Если задача простая, а ее решение выглядит громоздким и запутанным — это сигнал, что вы перешли черту.

Чтобы писать чисто и без перегрузки:

1. Изучите базу
   Начните с основ: PEP8, Google Python Style Guide. Изучайте исходники популярных библиотек — это эталоны того, как опытные разработчики пишут сложные вещи простым кодом.

2. Договоритесь в команде
   Составьте внутренние соглашения по стилю. Обсудите и зафиксируйте правила именования, организации модулей и другие важные аспекты — придите к общему пониманию. 

3. Используйте инструменты с умом
   Настройте форматтеры — они must have для автоматического поддержания стиля. Линтеры применяйте как советников, а не как догму — они полезны для поиска проблем, но не должны диктовать каждый шаг.

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

5. Решайте конкретные задачи
   Разрабатывайте функционал под актуальные требования бизнеса. Не торопитесь строить архитектуру «на вырост» и закладывать возможности «на будущее». Сначала сделайте простое рабочее решение.

Главный принцип, который стоит запомнить: ценность кода измеряется его понятностью для команды и полезностью для проекта. Мы пишем код не для того, чтобы блеснуть умом, а для того, чтобы он решал бизнес-задачи и был легко поддерживаемым.

А вы часто сталкивались с оверинжинирингом на практике? Поделитесь в комментариях самыми запоминающимися примерами, когда стремление к «идеалу» только мешало.