Por que arquivos utils.py e helpers.py prejudicam o design do código e como organizar regras de negócio de forma escalável

Arquivos como utils.py, helpers.py ou common.py costumam nascer de uma boa intenção: evitar repetição e concentrar lógicas “reutilizáveis”. No começo, essa escolha parece organizada e eficiente, porque reduz duplicações rápidas e dá uma sensação de padronização. Com o tempo, porém, a pasta de utilidades tende a virar um lugar genérico onde qualquer coisa “que não se encaixa” é colocada. Esse acúmulo corrói a clareza, aumenta o risco de mudanças e cria um ambiente em que ninguém tem certeza do impacto de tocar em funções compartilhadas.

Uma alternativa mais sustentável é tratar reutilização como consequência de um bom desenho, e não como um destino central. Em vez de empilhar funções sem contexto em um arquivo único, o comportamento passa a morar perto do assunto ao qual pertence, com nomes que descrevem intenção. Essa organização reduz ambiguidade, separa responsabilidades e facilita testes e evolução. O resultado costuma ser um código mais previsível, com limites claros e menos surpresas quando o projeto cresce.

O que são “funções utilitárias” e por que parecem uma boa ideia

Uma função utilitária é uma função colocada em um módulo genérico para ser usada em muitas partes do sistema, normalmente com um nome amplo e sem ligação explícita com um domínio. Em projetos Python, isso costuma aparecer como um arquivo utils.py que reúne validações, formatações, pequenos cálculos, conversões e até regras de negócio. A promessa é reduzir duplicação, manter “um lugar único” para lógicas repetidas e acelerar o desenvolvimento. O problema é que a utilidade “genérica” muitas vezes não é realmente genérica, apenas parece ser no momento em que foi criada.

Quando um conjunto de funções vira um repositório de tudo, o módulo perde identidade e vira uma gaveta de peças soltas. Nomes como process_data, validate_input e format_date não carregam significado suficiente para indicar o que realmente acontece. Isso cria um custo cognitivo: ler o código exige abrir a função, entender os detalhes e descobrir se é aplicável. Em projetos em crescimento, esse custo passa a dominar o tempo de manutenção e revisão.

O problema central: utilitários removem contexto e intenção

Contexto é a informação que explica “por que” e “para quê” uma regra existe, não apenas “como” ela é executada. Funções utilitárias tendem a apagar esse contexto porque ficam distantes do domínio e recebem nomes genéricos. Ao importar algo como format_date, não fica claro se o formato é para nota fiscal, relatório, auditoria ou interface. A mesma ambiguidade aparece em validações: validate_input pode significar validação de login, cadastro, pagamento ou importação de arquivo.

Quando o nome e a localização carregam o domínio, a leitura fica mais honesta e previsível. Um import como billing.dates.format_invoice_date revela intenção e reduz a necessidade de investigar detalhes internos. Essa clareza não impede reutilização, apenas muda o “como” ela acontece: reutiliza-se dentro de um assunto, com limites e semântica explícitos. O código deixa de ser um conjunto de verbos genéricos e passa a ser uma história sobre o negócio.

Como utils.py cresce: a “gaveta de tralhas” do projeto

O primeiro sinal de alerta surge quando qualquer lógica “sem casa” vai parar em utils.py. Não há um dono claro do módulo, então ninguém se sente responsável por manter consistência ou remover o que ficou obsoleto. Com o tempo, o arquivo vira um inventário de ideias antigas, versões alternativas e funções que quase ninguém confia. A consequência é previsível: novas implementações começam a ser copiadas e coladas, porque procurar a função certa parece mais caro do que reescrever.

Esse tipo de crescimento cria uma falsa sensação de reutilização, mas na prática aumenta fragmentação e inconsistência. Funções semelhantes surgem com pequenas diferenças de comportamento, nomes parecidos e contratos pouco definidos. Mudanças passam a ser arriscadas, já que não existe um limite claro de impacto. A própria presença de muitas funções no mesmo lugar incentiva dependências cruzadas, e o módulo começa a importar coisas do sistema inteiro para “ajudar”, tornando-se ainda mais difícil de entender e testar.

Quando “helper” vira regra de negócio escondida

Regra de negócio é uma regra que existe por causa do funcionamento do domínio, como descontos, permissões, elegibilidade e políticas de cobrança. Quando uma regra de negócio vai parar em um utilitário, ela fica disfarçada de função neutra, mesmo sendo altamente específica. Isso costuma acontecer em cálculos de preço, imposto, frete, comissões, validações de status e decisões condicionais relacionadas a clientes ou pedidos. O risco é que outras partes do sistema reutilizem a função em um contexto diferente, aplicando uma política onde ela não deveria valer.

Outro efeito é a dificuldade de testar e evoluir. Regras de negócio mudam com frequência e precisam de testes focados e nomes claros. Em um arquivo de utilidades, a regra fica escondida entre formatações e conversões, e o time tende a tratá-la como “infraestrutura”. O resultado é um acoplamento silencioso: uma pequena mudança para um caso específico pode quebrar fluxos que dependiam do comportamento antigo sem perceber.

Acoplamento invisível: dependências e efeitos colaterais

Acoplamento é o grau de dependência entre partes do código. Funções utilitárias frequentemente começam puras, mas vão ganhando dependências para “resolver logo”: importam configurações, modelos, serviços externos, variáveis de ambiente e até fazem consultas a banco. Quando isso acontece dentro de um módulo genérico, o risco aumenta porque o local não “parece perigoso”. A função é chamada em vários lugares, e qualquer mudança de dependência se espalha como uma rachadura difícil de rastrear.

Efeito colateral é uma ação além de retornar um valor, como gravar em banco, enviar mensagem, registrar log, modificar estado global ou depender de horário atual. Utilitários com efeito colateral são especialmente problemáticos, pois viram “caixinhas surpresa”. Em vez de serem pequenas ferramentas previsíveis, passam a executar decisões e ações ocultas. Isso reduz confiabilidade, dificulta simulação em testes e aumenta a chance de falhas em cascata.

Cheiro de design: o sinal de que falta “um lugar certo” para a lógica

Cheiro de design é um indício de que a estrutura do código pode estar desalinhada com o domínio. Uma pasta de utilidades enorme geralmente significa que o sistema não definiu bem seus conceitos e limites. Em um desenho mais saudável, o comportamento vive perto dos dados e dos conceitos que representa. Isso faz com que nomes reflitam intenção, e não apenas implementação, e cada parte do sistema tenha responsabilidade clara.

O ponto central não é “nunca reutilizar”, e sim “reutilizar com significado”. Em vez de perguntar se algo pode ser reutilizado, a pergunta mais estável é qual conceito está sendo representado. Quando a resposta existe, o módulo ou classe se forma naturalmente. Essa mudança reduz ambiguidade e cria caminhos de evolução, porque cada conceito pode crescer sem engolir o projeto inteiro.

Padrão melhor 1: comportamento em módulos de domínio (em vez de utilidades globais)

Um módulo de domínio é um arquivo ou pacote que representa um assunto do sistema, como autenticação, cobrança, pedidos ou relatórios. Colocar regras e validações nesses módulos dá contexto imediato, pois o nome do pacote já explica o motivo de existir. Isso melhora a leitura e reduz o risco de reutilização incorreta, porque a localização “avisa” quando algo é específico. Abaixo aparece um exemplo comparando o “antes” genérico com o “depois” contextualizado.

# Antes: utils.py (genérico e fácil de crescer sem controle)
# utils.py
import re

def is_valid_email(email: str) -> bool:
    padrao = r"^[^@\s]+@[^@\s]+\.[^@\s]+$"
    return bool(re.match(padrao, email))


# Depois: users/validation.py (com contexto)
# users/validation.py
import re

def is_valid_email(email: str) -> bool:
    """
    Valida e-mail no contexto de usuários.
    Mantém a regra perto do domínio de cadastro/autenticação.
    """
    padrao = r"^[^@\s]+@[^@\s]+\.[^@\s]+$"
    return bool(re.match(padrao, email))

Mesmo quando a implementação é idêntica, a organização muda o significado. A função deixa de ser uma ferramenta solta e passa a ser parte explícita do domínio de usuários. Essa separação também facilita descobrir onde colocar regras adicionais, como e-mails bloqueados ou validações específicas. O resultado é um crescimento mais ordenado, com menos “mistura” de assuntos.

Padrão melhor 2: módulos pequenos e intencionais, em vez de um arquivo gigante

Em Python, criar módulos é barato e costuma ser mais simples do que manter um arquivo monolítico de utilidades. Um módulo pequeno concentra um tipo de transformação ou regra, mantendo um contrato mais claro. Em vez de reunir datas, dinheiro, strings, serialização e validação em um único lugar, a separação cria limites naturais. Isso também melhora testes, porque cada módulo tem menos responsabilidades e menos combinações de dependências.

Uma organização ainda melhor aparece quando os módulos são agrupados por subdomínios, como billing, orders e reports. Funções de data para relatórios raramente são idênticas às de cobrança, porque formatos e regras de negócio mudam. Ao separar por domínio, o nome do módulo passa a carregar significado. A reutilização continua possível, mas passa a ser uma decisão consciente, e não um efeito colateral de “pegar do utils”.

Padrão melhor 3: usar classes quando estado, configuração ou regras variáveis importam

Uma classe faz sentido quando existe estado, isto é, dados que precisam ser lembrados entre chamadas, como país, moeda, regime fiscal ou políticas configuráveis. Funções utilitárias são frequentemente usadas para esconder dependências, recebendo muitos parâmetros ou buscando configurações globais. Ao transformar em classe, as dependências ficam explícitas e agrupadas, e o método passa a operar com um contexto claro. Isso melhora testes e permite extensões sem multiplicar condicionais.

O exemplo a seguir mostra a diferença entre uma função com regras variáveis e uma classe que carrega o contexto. O objetivo não é “usar classe sempre”, e sim usar quando a regra depende de parâmetros que representam um conceito. Com isso, a lógica fica mais fácil de evoluir, como adicionar exceções por estado, faixas de produto ou regimes especiais. A estrutura passa a refletir a realidade do domínio.

# Antes: função utilitária com regras variáveis e contexto fraco
def calcular_imposto(valor: float, pais: str) -> float:
    if pais == "BR":
        return valor * 0.12
    if pais == "PT":
        return valor * 0.23
    return valor * 0.10


# Depois: classe com dependência explícita e ponto de extensão
class CalculadoraImposto:
    def __init__(self, pais: str):
        self.pais = pais

    def calcular(self, valor: float) -> float:
        if self.pais == "BR":
            return valor * 0.12
        if self.pais == "PT":
            return valor * 0.23
        return valor * 0.10


# Exemplo de uso
calculadora = CalculadoraImposto(pais="BR")
total_imposto = calculadora.calcular(100.0)

Padrão melhor 4: o dado “possui” o comportamento (métodos no objeto)

Quando uma lógica opera principalmente sobre uma entidade, como pedido, fatura ou usuário, faz sentido colocar o comportamento na própria entidade. Isso é chamado de proximidade comportamental, porque o código fica perto do dado que ele explica. Em vez de uma função solta como is_order_refundable, um método como order.is_refundable expressa melhor a intenção. A leitura fica mais natural e reduz a necessidade de descobrir onde a regra está escondida.

Esse padrão também melhora consistência: se existem várias partes do sistema verificando reembolso, todas podem depender do mesmo método. A entidade vira o lugar “oficial” da regra, evitando divergência de implementações. Quando a política muda, a alteração ocorre em um local com nome e responsabilidade claros. A seguir aparece um exemplo simples com regras explícitas.

from dataclasses import dataclass
from datetime import datetime, timedelta

@dataclass(frozen=True)
class Pedido:
    criado_em: datetime
    status: str  # exemplo: "PAGO", "ENVIADO", "CANCELADO"

    def é_reembolsável(self, agora: datetime) -> bool:
        """
        Regra de negócio: reembolso permitido em até 7 dias para pedidos pagos
        e não enviados.
        """
        prazo = self.criado_em + timedelta(days=7)
        dentro_do_prazo = agora <= prazo
        status_permitido = self.status == "PAGO"
        return dentro_do_prazo and status_permitido


# Exemplo de uso
pedido = Pedido(criado_em=datetime(2026, 1, 10), status="PAGO")
pode_reembolsar = pedido.é_reembolsável(agora=datetime(2026, 1, 12))

Padrão melhor 5: composição funcional com módulos por “pipeline”, não por conveniência

Composição funcional é a ideia de montar comportamentos complexos combinando funções pequenas, cada uma fazendo uma transformação clara. O problema não é ter funções auxiliares, e sim agrupá-las sem estrutura. Ao separar por etapas, como parsing, normalização e validação, a reutilização ocorre de modo previsível. Cada módulo representa uma fase, e as funções ganham nomes que refletem o papel naquele fluxo.

No exemplo abaixo, funções relacionadas a CSV ficam no mesmo lugar e são combinadas de forma explícita. Isso evita um utilitário genérico chamado process_csv que “faz tudo” e ninguém sabe exatamente o quê. A divisão em etapas torna testes mais simples, pois cada função pode ser validada isoladamente. O sistema também fica mais flexível para lidar com variações de entrada sem criar um monólito.

# parsing_csv.py
import csv
from typing import List, Dict, TextIO

def ler_csv(arquivo: TextIO) -> List[Dict[str, str]]:
    leitor = csv.DictReader(arquivo)
    return [linha for linha in leitor]


# normalizacao_csv.py
from typing import List, Dict

def normalizar_cabecalhos(linhas: List[Dict[str, str]]) -> List[Dict[str, str]]:
    linhas_normalizadas = []
    for linha in linhas:
        nova = {chave.strip().lower(): valor.strip() for chave, valor in linha.items()}
        linhas_normalizadas.append(nova)
    return linhas_normalizadas


# validacao_csv.py
from typing import List, Dict

def validar_colunas_obrigatorias(linhas: List[Dict[str, str]], colunas: List[str]) -> None:
    for i, linha in enumerate(linhas):
        for coluna in colunas:
            if coluna not in linha or linha[coluna] == "":
                raise ValueError(f"Linha {i}: coluna obrigatória ausente: {coluna}")

“Mas utilitários são mais rápidos”: custo imediato vs. custo acumulado

Funções utilitárias realmente aceleram o curto prazo, porque exigem pouca reflexão sobre arquitetura. O custo aparece depois, quando o arquivo cresce e as dependências ficam confusas. O tempo economizado na criação é pago com juros na leitura, depuração e refatoração. Em projetos com mais pessoas e mais tempo de vida, esse custo acumulado costuma superar o ganho inicial.

Ao organizar comportamento com significado, o desenvolvimento pode parecer mais lento no início, porque exige nomear conceitos e separar módulos. Em troca, a manutenção fica mais estável, pois cada parte tem um lugar esperado. Alterações passam a ser mais seguras, já que o impacto é mais previsível. O código fica menos dependente de “memória do time” e mais dependente de estrutura explícita.

Quando funções utilitárias são aceitáveis (e como limitar o estrago)

Há casos em que utilitários fazem sentido, especialmente quando são realmente genéricos e independentes do domínio. Funções puras (sem efeitos colaterais), sem estado e agnósticas de contexto podem viver em um módulo compartilhado sem causar grandes danos. Exemplos típicos incluem normalização simples de texto, pequenas funções matemáticas e conversões básicas. A principal característica é que a função faria sentido em qualquer projeto, não apenas naquele sistema específico.

Mesmo nesses casos, um cuidado importante é evitar que o módulo genérico comece a importar partes do domínio. Se um utilitário precisa de modelos, configurações de negócio ou regras específicas, ele já não é mais utilitário. Outra prática saudável é manter o módulo pequeno e bem nomeado, como strings.py ou math.py, em vez de utils.py. O nome mais específico cria uma barreira natural contra virar uma gaveta de tralhas.

Teste simples para decidir: utilitário ou lógica de domínio

Uma decisão consistente nasce de perguntas que revelam contexto escondido. Se a lógica pertence a uma área específica, então ela é de domínio e deve morar perto desse domínio. Se ela codifica política, exceções e regras do negócio, também é domínio, mesmo que pareça “só um cálculo”. Se ela assume formatos internos, modelos ou estruturas específicas do sistema, então não é genérica o suficiente para ser utilitário.

Outra pista forte é imaginar se o nome mudaria fora do projeto. Uma função chamada format_date provavelmente mudaria quando o objetivo é “data da fatura” ou “data do relatório”. Quando isso acontece, o nome genérico está escondendo significado, e o lugar correto é um módulo com contexto. A organização por intenção reduz dúvidas e melhora a comunicação do próprio código.

Fim: reutilização com significado, não com acúmulo

Funções utilitárias não são um erro por existirem, e sim por virarem o destino padrão de qualquer comportamento sem endereço. Quando isso acontece, contexto desaparece, regras de negócio se escondem e o acoplamento cresce sem ser percebido. O resultado é um código mais difícil de ler, mais arriscado de alterar e mais caro de manter, mesmo que pareça “organizado” por estar centralizado. A clareza não nasce da centralização, e sim de nomes e lugares que carregam intenção.

Uma estrutura mais saudável coloca comportamento perto do conceito que ele representa, seja em módulos de domínio, classes com dependências explícitas, métodos nas entidades ou pipelines por etapa. A reutilização continua existindo, mas deixa de ser um atalho e passa a ser um efeito de bom design. Com limites claros, o sistema cresce com menos medo de tocar em partes compartilhadas. O código passa a explicar o que é, por que existe e como deve ser usado, sem precisar de uma gaveta genérica para “resolver depois”.