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,data2economizam 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
inum 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 (
ifdentro defordentro deif). - 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.
Leia também
- Estimativa de prazo: por que erramos e como errar menos21 de novembro de 2026 · 5 min
- i18n no Next.js: site em vários idiomas sem dor20 de novembro de 2026 · 5 min
- Padrões de projeto: Strategy, Observer e Factory19 de novembro de 2026 · 4 min
- Reels virais sem aparecer: fluxo com Claude Code18 de novembro de 2026 · 5 min