Anti-Patterns: evite problemas conhecidos

Todo mundo já escreveu código ruim, eu muitas vezes. A primeira versão costuma ser a mais tenebrosa: é ela que sai quando você resolve um problema pela primeira vez, com prazo correndo, sem saber ainda o que aquela escolha vai custar daqui a seis meses.

Boa parte desses problemas já foi catalogada. Quando a mesma solução ruim reaparece em projetos diferentes, times diferentes e linguagens diferentes, alguém dá um nome a ela. Com o nome, dá pra reconhecer o problema antes de escrevê-lo de novo.

Anti-patterns são esses nomes. São soluções que parecem razoáveis na hora de escrever e criam trabalho depois, na hora de ler, mudar ou confiar no que está lá. Este post mostra um exemplo inteiro do espaguete, lista os que aparecem com frequência em projeto real e reescreve o mesmo código com as escolhas trocadas.

Conceitos fundamentais

Um exemplo inteiro: código espaguete

O código espaguete é o anti-pattern mais citado, e o mais fácil de reconhecer depois que você viu um. Não tem estrutura, não tem contrato, não tem intenção visível. O código funciona, e mudar uma linha dele exige reler o arquivo inteiro pra saber o que mais deixa de funcionar.

// Exemplo propositalmente RUIM
// Código todo misturado, sem conceitos claros

realizaVenda(123);

function realizaVenda(x) {
  let resultado;

  // nomes ruins
  let p = buscaPedido(x);

  if (p != null) {
    if (p.itens && p.itens.length > 0) {
      if (!p.c.inadimplente) {
        // começa a fazer um monte de coisa no meio
        if (p.total > 100) {
          p.desconto = 10;
        } else {
          p.desconto = 0;
        }

        apply(p);

        function apply(p) {
          if (p.desconto) {
            p.total = p.total - p.desconto;
          }
        }

        let salvo = salvaPedido(p);

        if (salvo) {
          resultado = salvo;

          // lógica aleatória no meio
          if (Math.random() > 0.5) {
            console.log("Log qualquer");
          } else {
            console.warn("Outro log");
          }
        } else {
          resultado = null;
        }
      } else {
        // mais lógica aninhada com função no meio
        notify(detalhesDoPedido);
        resultado = false;

        // nomes ruins e mistura de português com inglês
        function notify(p) {
          console.log("cliente inadimplente", p?.cliente?.nome);
          return true;
        }
      }
    } else {
      resultado = undefined;
    }
  } else {
    resultado = null;
  }

  // código morto
  if (false) {
    console.log("nunca executa");
  }

  return resultado;

  function salva(p) {
    if (!p) return;
    if (p.total < 0) return null;
    return { ...p, salvo: true };
  }
}

Pra chegar na regra do desconto, você entra em vários if's. Pra descobrir o que a função devolve, precisa achar as cinco atribuições de resultado espalhadas pelos if e simular, uma a uma, qual delas vale pro pedido que você tem em mãos. A função salva no rodapé não é chamada por ninguém: quem grava o pedido é salvaPedido, que nem está definida ali. E o Math.random() escolhe qual log sai, então a mesma venda produz saídas diferentes a cada execução. 😅

O que torna esse código caro

Os problemas abaixo estão todos naquele arquivo. Cada linha da tabela mostra o que aparece no exemplo e o que entra no lugar.

Nomes e legibilidade

Controle de fluxo

Retorno e contrato

Estrutura e design

Estado e mutabilidade

Efeitos colaterais e previsibilidade

Esses problemas raramente aparecem sozinhos, e um facilita o outro. Com let resultado declarado no topo, tratar mais um caso custa uma linha, então o próximo if entra sem resistência. Com quatro níveis de indentação já no arquivo, introduzir um retorno antecipado exige desmontar os quatro, e quem está com prazo escreve o quinto.

Outros anti-patterns comuns em projetos reais

Fora do espaguete, existem padrões que passam na revisão porque cada um deles, isolado, parece razoável.

Modelagem e contrato de dados

UI acoplada ao que não é dela

Design de código

Fluxo e controle

O mesmo código, reescrito

As escolhas são as da coluna da direita: orquestrador no topo, auxiliares abaixo pela regra de descida (step down rule), densidade visual e nomes que dizem a intenção.

// ✅ Código narrativo
// Orquestrador no topo, auxiliares abaixo pela regra de descida (step down),
// densidade visual e nomes expressivos.

import { buscaPedido, salvaPedido } from "pedidos/repositorio.js";
import { notificaInadimplencia } from "notificacoes/inadimplencia.js";
import { aplicaDescontos } from "pedidos/desconto.js";

const VENDA_APROVADA = "APROVADA";
const VENDA_RECUSADA = "RECUSADA";

const venda = await realizaVenda(123);

async function realizaVenda(codigoDoPedido) {
  const detalhesDoPedido = await buscaPedido(codigoDoPedido);

  if (!temItensParaFaturar(detalhesDoPedido)) {
    const vendaSemItens = recusaVenda("PEDIDO_SEM_ITENS");
    return vendaSemItens;
  }

  if (detalhesDoPedido.cliente.inadimplente) {
    notificaInadimplencia(detalhesDoPedido);

    const vendaBloqueada = recusaVenda("CLIENTE_INADIMPLENTE");
    return vendaBloqueada;
  }

  const notaFiscal = await emiteNotaFiscal(detalhesDoPedido);
  const vendaConcluida = aprovaVenda(notaFiscal);
  return vendaConcluida;
}

function temItensParaFaturar(pedido) {
  const itens = pedido?.itens ?? [];
  const temAlgumItem = itens.length > 0;
  return temAlgumItem;
}

function recusaVenda(motivo) {
  const venda = { status: VENDA_RECUSADA, motivo, notaFiscal: null };
  return venda;
}

async function emiteNotaFiscal(pedido) {
  const pedidoComDesconto = aplicaDescontos(pedido);
  const notaFiscal = await salvaPedido(pedidoComDesconto);
  return notaFiscal;
}

function aprovaVenda(notaFiscal) {
  const venda = { status: VENDA_APROVADA, motivo: null, notaFiscal };
  return venda;
}

O fluxo principal são quatro passos, lidos de cima pra baixo: busca o pedido, recusa se não tem item, recusa se o cliente está inadimplente, fatura. Cada return tem uma const nomeada logo acima, então o nome diz qual dos três desfechos é aquele.

O contrato agora é um só. Nos três caminhos, a função devolve um objeto com status, motivo e notaFiscal. Quem chama lê venda.status e sabe o que aconteceu, e no caso da recusa o motivo diz qual das duas regras barrou a venda. Compare com o exemplo anterior, onde false e undefined significavam coisas diferentes e nenhum dos dois explicava o quê.

As auxiliares ficam abaixo do orquestrador, cada uma logo depois de onde é chamada, e você só desce até elas se quiser o detalhe. É a regra de descida: a leitura vai do passo para o detalhe, de cima para baixo. Como são funções irmãs, e não presas dentro de realizaVenda, cada uma se testa isolada, e quando outra venda precisar barrar um pedido, recusaVenda já está lá pra reusar. aplicaDescontos devolve o pedido com desconto em vez de alterar o que recebeu, então nenhuma função altera objeto que veio de fora.

Um idioma só, do começo ao fim

O código acima está em português porque o exemplo ruim também está, e assim os dois se comparam linha a linha. Fora de um post, eu escreveria os dois em inglês.

O defeito do exemplo ruim nunca foi o português. Foi a mistura dos dois: realizaVenda e buscaPedido estão no mesmo arquivo que apply e notify, e uma função chamada salva fica logo abaixo de outra chamada salvaPedido. Chamam isso de portuglês, e o custo aparece toda vez que você vai chamar alguma coisa: era notify ou notifica? O autocomplete do editor não resolve, porque ele lista os dois. Você abre o arquivo pra conferir, e repete isso a cada nome do projeto.

As duas línguas se defendem, e eu recomendo o inglês por um motivo prático: metade do arquivo já está em inglês e isso não muda. if, return, length, console.log e Math.random vêm da linguagem. Com os nomes em inglês, a linha inteira se lê de uma vez, sem trocar de idioma no meio. É também o idioma da documentação que você vai consultar, da mensagem de erro que vai colar no buscador e da biblioteca que vai instalar.

Abaixo, o mesmo código, com essa convenção aplicada. É a versão que eu recomendo.

// ✅ Recomendado: um idioma só, do começo ao fim.
// Mesma estrutura do exemplo anterior, nomes em inglês.

import { findOrder, saveOrder } from "orders/repository.js";
import { notifyOverdueCustomer } from "notifications/overdue.js";
import { applyDiscounts } from "orders/discount.js";

const SALE_APPROVED = "APPROVED";
const SALE_REJECTED = "REJECTED";

const sale = await sellOrder(123);

async function sellOrder(orderId) {
  const orderDetails = await findOrder(orderId);

  if (!hasBillableItems(orderDetails)) {
    const saleWithoutItems = rejectSale("ORDER_WITHOUT_ITEMS");
    return saleWithoutItems;
  }

  if (orderDetails.customer.isOverdue) {
    notifyOverdueCustomer(orderDetails);

    const blockedSale = rejectSale("CUSTOMER_OVERDUE");
    return blockedSale;
  }

  const taxInvoice = await issueTaxInvoice(orderDetails);
  const completedSale = approveSale(taxInvoice);
  return completedSale;
}

function hasBillableItems(order) {
  const items = order?.items ?? [];
  const hasAnyItem = items.length > 0;
  return hasAnyItem;
}

function rejectSale(reason) {
  const rejectedSale = { status: SALE_REJECTED, reason, taxInvoice: null };
  return rejectedSale;
}

async function issueTaxInvoice(order) {
  const discountedOrder = applyDiscounts(order);
  const taxInvoice = await saveOrder(discountedOrder);
  return taxInvoice;
}

function approveSale(taxInvoice) {
  const approvedSale = { status: SALE_APPROVED, reason: null, taxInvoice };
  return approvedSale;
}

A estrutura é idêntica à versão em português, e é isso que a comparação mostra: trocar o idioma não conserta nem estraga nada do que as tabelas apontaram. São dois assuntos separados.

O idioma único vale para o código: nomes de variável, função e constante. Já as mensagens, rótulos, tags e botões que aparecem na tela ficam na língua de quem usa o sistema, porque existem pra ajudar essa pessoa. CUSTOMER_OVERDUE é um código interno em inglês, e a frase que o cliente vê sai traduzida na borda: “Não foi possível concluir a compra: há faturas em aberto.”

Um nome do exemplo merece explicação: nota fiscal virou taxInvoice, e não invoice. São dois documentos diferentes, e vale conhecer a distinção antes de escolher a palavra:

• Fatura é o documento comercial que detalha o que foi vendido e cobra o valor. Não tem validade tributária e não é obrigatória por lei. Em inglês, é ela que se chama invoice.
• Nota fiscal é o documento fiscal obrigatório, que registra a operação para o fisco e comprova o recolhimento do imposto.

Hoje o mais comum é a NF-e trazer a fatura e suas parcelas dentro da própria nota, no grupo de cobrança. Pela Lei das Duplicatas (Lei 5.474/1968, art. 1º) é o inverso: a fatura fica por cima e reúne várias notas numa cobrança só.

Em um sistema que emite nota fiscal e fatura, usar invoice para representar a nota fiscal ocupa um nome que faz mais sentido para a fatura. Quando ela for adicionada ao sistema, será preciso recorrer a nomes menos claros, como invoice2 ou billingInvoice. Por isso, no exemplo acima, foi utilizado taxInvoice. Essa é uma sugestão, não uma regra: se o sistema trabalha apenas com um desses documentos, invoice é um nome perfeitamente adequado.

Quem decide isso é o time, e a decisão depende do contexto do projeto. O que ajuda em qualquer contexto é deixar a escolha registrada num glossário. No Simula Impostos, um app que escrevi pra comparar encargos tributários, o README traz um: os identificadores estão em inglês, a interface que o contador usa está em português, e a tabela liga os dois.

São cerca de 30 linhas no README do projeto. O contador pede uma mudança no “Emitente”, e você sabe que o campo é issuer sem abrir o código pra conferir. Quem entra no projeto lê o glossário uma vez, em vez de descobrir o padrão por tentativa e acrescentar um terceiro nome.

É o que o Code Style que sigo tenta resolver: não qual convenção é a certa, mas onde ela está anotada.

As siglas vêm depois

Existem várias siglas em volta desse assunto:

• DDD (Domain-Driven Design · modelar o código na linguagem do negócio)
• TDD (Test-Driven Development · escrever o teste antes do código)
• SOLID (cinco princípios de design orientado a objetos)
• YAGNI (You Aren’t Gonna Need It · não construa o que ainda não pediram)

Todas ajudam, e nenhuma delas é o ponto de partida. O ponto de partida é escrever código que a próxima pessoa consiga ler. As siglas dão nome próprio a hábitos que você já vai estar praticando quando chegar nelas.

Se o código que você mantém hoje já tem vários desses padrões, a saída não precisa ser reescrever tudo. Cada um deles entrou por um commit separado, e sai do mesmo jeito: na próxima vez que abrir aquele arquivo pra mudar uma regra, corrija um.

Happy coding!

Referências

• Code Style, o guia de convenções que sigo
• Refactoring Guru: Code Smells
• Clean Code, de Robert C. Martin
• SOLID Principles
• YAGNI