Clean code na prática: nomes, funções e comentários

Três hábitos que deixam o código mais fácil de ler e manter, escolher nomes que revelam intenção, escrever funções que fazem uma coisa só e usar comentários pra explicar o porquê, sem virar dogma.


Código é lido muito mais vezes do que é escrito. Quem escreve passa uma tarde nele, e quem mantém (muitas vezes você mesmo, seis meses depois) passa anos tentando entender o que ele faz. Clean code não é estética nem perfeccionismo, é reduzir o esforço de leitura. Três hábitos resolvem a maior parte do problema.

1. Nomes que revelam intenção

Um bom nome responde "o que é isso?" e "pra que serve?" sem você precisar ler a implementação.

// difícil
const d = 7;
function calc(a, b) {
  return a * b * 0.1;
}
 
// claro
const PRAZO_DE_ENTREGA_EM_DIAS = 7;
function calcularComissao(valorDaVenda, quantidade) {
  const TAXA_DE_COMISSAO = 0.1;
  return valorDaVenda * quantidade * TAXA_DE_COMISSAO;
}

Algumas regras que ajudam:

  • Funções são verbos, variáveis são substantivos. buscarUsuario, usuarioAtivo.
  • Booleanos soam como pergunta. estaLogado, temPermissao, podeEditar.
  • Evite abreviações obscuras. usr, tmp, data2 economizam três letras e custam minutos de leitura.
  • Nada de números mágicos. if (status === 3) não diz nada, if (status === STATUS_CANCELADO) diz.
  • Tamanho proporcional ao escopo. Um i num loop de três linhas é aceitável. Uma variável usada em cem linhas precisa de um nome completo.

Se você precisa de um comentário pra explicar o que uma variável guarda, o nome está errado.

2. Funções que fazem uma coisa só

Uma função longa que valida, calcula, salva e envia e-mail é difícil de testar, difícil de reaproveitar e difícil de entender. Compare:

async function finalizarPedido(pedido) {
  if (!pedido.itens.length) throw new Error("Pedido vazio");
 
  let total = 0;
  for (const item of pedido.itens) {
    total += item.preco * item.quantidade;
  }
  if (pedido.cupom === "PRIMEIRA") total *= 0.9;
 
  await db.pedido.create({ data: { ...pedido, total } });
  await enviarEmail(pedido.cliente.email, `Total: ${total}`);
}

Dividida pelos níveis de abstração:

async function finalizarPedido(pedido) {
  validarPedido(pedido);
  const total = calcularTotal(pedido);
  await salvarPedido(pedido, total);
  await notificarCliente(pedido.cliente, total);
}
 
function validarPedido(pedido) {
  if (!pedido.itens.length) throw new Error("Pedido vazio");
}
 
function calcularTotal(pedido) {
  const subtotal = pedido.itens.reduce(
    (soma, item) => soma + item.preco * item.quantidade,
    0
  );
  return pedido.cupom === "PRIMEIRA" ? subtotal * 0.9 : subtotal;
}

Agora finalizarPedido se lê como um resumo da história, e cada detalhe mora numa função que você testa sozinha, como mostrei no post sobre testes unitários. É o mesmo espírito do princípio da responsabilidade única do post sobre SOLID, aplicado numa escala menor.

Sinais de que uma função está grande demais:

  • Você precisa de um comentário pra separar "blocos" dentro dela.
  • Ela tem mais de três níveis de indentação (if dentro de for dentro de if).
  • O nome precisa de "e" pra descrever o que ela faz: validarESalvar.
  • Passa de uma tela de altura.

Retorne cedo em vez de aninhar

Condições aninhadas escondem o caminho principal:

// aninhado
function processar(usuario) {
  if (usuario) {
    if (usuario.ativo) {
      if (usuario.temPlano) {
        return liberarAcesso(usuario);
      }
    }
  }
  return null;
}
 
// retorno antecipado
function processar(usuario) {
  if (!usuario) return null;
  if (!usuario.ativo) return null;
  if (!usuario.temPlano) return null;
 
  return liberarAcesso(usuario);
}

Os casos de saída vêm primeiro, e o fluxo feliz fica no final, sem indentação.

3. Comentários: o porquê, não o quê

Um comentário que repete o código só atrapalha, porque envelhece e passa a mentir:

// incrementa o contador em 1
contador++;
 
// verifica se o usuário é maior de idade
if (usuario.idade >= 18) { ... }

O código já diz isso. Comentários bons explicam o que o código não consegue expressar: a decisão por trás.

// A API de frete retorna 200 mesmo em erro, então precisamos
// checar o campo "sucesso" no corpo da resposta.
if (!resposta.sucesso) throw new Error(resposta.mensagem);
 
// Esperamos 5 tentativas porque o provedor de e-mail
// costuma falhar por alguns segundos após um deploy deles.
const MAX_TENTATIVAS = 5;

Esses comentários registram contexto, limitações de sistemas externos e o motivo de uma escolha que pareceria estranha. Isso é informação que ninguém recupera lendo apenas o código.

Antes de escrever um comentário, tente expressar a ideia no código: extraia uma função com nome claro, ou renomeie a variável. Só se ainda faltar o porquê, comente.

E código comentado (blocos de código antigo desativados) não deve ficar no repositório. O Git guarda o histórico, apague sem medo.

Cuidado com o dogma

Clean code vira problema quando é levado ao extremo. Dividir tudo em funções de duas linhas obriga o leitor a pular por dez arquivos pra entender um fluxo simples. Abstrair antes de ter duas ou três repetições reais gera código genérico demais. Nenhuma regra substitui o critério.

A pergunta que vale mais que qualquer regra: uma pessoa que nunca viu esse código entende o que ele faz em poucos minutos? Se sim, está bom. Se não, descubra onde ela tropeçaria e conserte esse ponto.

Fechando

Nomes que revelam intenção, funções que fazem uma coisa e comentários que explicam o porquê custam pouco na hora de escrever e economizam muito em cada leitura futura. Não é sobre seguir um manual, é sobre deixar o próximo leitor, que provavelmente será você, com menos trabalho.

Direto na sua
caixa de entrada.

Um aviso por e-mail sempre que eu publicar um post novo. Sem spam, sem newsletter chata, só isso.