Venho arquitetando software há 47 anos, e finalmente decifrei o código sobre organização de código: não organize. Cada arquivo que você cria é uma troca de contexto. Cada import é sobrecarga cognitiva. Cada pasta é um crime contra a produtividade.

O número ótimo de arquivos em qualquer projeto é um.

A Matemática dos Arquivos

Vamos fazer uma matemática simples:

Número de Arquivos Statements de Import Coisas Que Podem Quebrar
1 0 1
5 12 60
50 200 5.000
500 3.000 ∞

Vê o padrão? Mais arquivos = exponencialmente mais problemas. Um arquivo = um problema. Simples.

A God Class: Arquitetura Divina

Eles chamam de “anti-pattern.” Eu chamo de eficiência:

# app.py - O único arquivo que você vai precisar
# Linhas 1-50.000: Gerenciamento de usuários
# Linhas 50.001-100.000: Processamento de pedidos
# Linhas 100.001-150.000: Handling de pagamentos
# Linhas 150.001-200.000: Templates de email (como strings)
# Linhas 200.001-250.000: CSS (também como strings)
# Linhas 250.001-300.000: Documentação (em comentários)
# Linhas 300.001-500.000: Dados de teste (hardcoded)

class App:
    def __init__(self):
        self.users = {}
        self.orders = {}
        self.payments = {}
        self.emails = {}
        self.config = {}
        self.cache = {}
        self.database = None
        self.http_client = None
        self.logger = print
        self.everything_else = {}
    
    # ... 15.000 métodos seguem

Como o XKCD 1205 mostra, tempo gasto automatizando deve ser menor que tempo gasto fazendo. Tendo um arquivo, você gasta zero tempo navegando entre arquivos. Isso é ROI infinito.

“Mas como você encontra qualquer coisa num arquivo de 500.000 linhas?”

Ctrl+F.

É isso. É o sistema inteiro.

# Meu workflow de navegação:
1. Ctrl+F
2. Digita algo que pode estar lá
3. Aperta Enter 47 vezes
4. Esperança
5. Se não encontrou, não existe

IDEs modernas com seu “Go to Definition” e “Find All References” só estão deixando desenvolvedores preguiçosos. No meu tempo, a gente scrollava. Por HORAS.

Estrutura de Projeto Real

Aqui está meu projeto de produção:

legendary-ecommerce/
└── app.py (847.293 linhas)

Compare com um projeto “moderno”:

modern-ecommerce/
├── src/
│   ├── controllers/
│   │   ├── user/
│   │   │   ├── __init__.py
│   │   │   ├── create.py
│   │   │   ├── read.py
│   │   │   └── ... (mais 37 arquivos)
│   │   ├── order/
│   │   └── ... (mais 500 pastas)
│   ├── services/
│   ├── repositories/
│   ├── domain/
│   ├── infrastructure/
│   └── ... (mais 10.000 arquivos)

Você sabe o que o Chefe Cabeça-Pontuda do Dilbert diria? “Eu não entendo nenhum dos dois, mas o com menos arquivos parece mais simples, então faz esse.”

Benefícios do Controle de Versão

Com um arquivo, conflitos de merge são garantidos, o que significa:

  1. Todos os devs devem coordenar cada commit
  2. Isso força comunicação
  3. Comunicação é uma “best practice”
  4. Portanto, um arquivo = best practice
# Workflow de Git com um arquivo
git pull  # CONFLICT in app.py
git stash
git pull
git stash pop  # CONFLICT in app.py
# Repete até alguém desistir de raiva

Otimização de Performance

Compiladores e interpretadores amam um arquivo:

# Sem overhead de import
# Sem lookups no sistema de arquivos
# Sem complexidade de cache de módulos
# Apenas 500.000 linhas de código puro e cru

# Tempo de startup: 47 minutos
# Mas apenas UMA VEZ por deploy

Refatoração Simplificada

Precisa refatorar? Em um projeto multi-arquivo, você precisa:

  1. Encontrar todos os usos
  2. Atualizar múltiplos arquivos
  3. Corrigir imports
  4. Atualizar testes
  5. Corrigir mais imports

Em um único arquivo:

  1. Ctrl+H (Substituir Tudo)
  2. Pronto

O One-Liner Definitivo

Aqui está meu código de produção mais elegante:

// app.js
eval(require('fs').readFileSync('all_the_code.txt', 'utf8').split('\n').map(line => line.trim()).filter(line => line && !line.startsWith('//')).join(';'))

Um arquivo. Uma linha. Um sonho.

Conclusão

Pare de criar arquivos. Pare de criar pastas. Pare de “organizar.” Cada abstração é uma mentira que contamos para nos sentirmos profissionais.

Engenheiros seniores de verdade sabem: todo código eventualmente vira uma grande bola de lama. Por que lutar contra o inevitável? Comece lá.

A IDE do autor crashou 47 vezes enquanto escrevia este artigo. Ela ficava sem memória tentando syntax-highlight o app.py.