Você abre o arquivo e encontra $data. De novo.
Sabe aquele método que você precisa ler três vezes? Não porque a lógica é difícil — a lógica é boba. É porque toda variável se chama a mesma coisa com sufixo diferente.
$data. $data2. $dataFinal. $result. $temp. $aux. $arr.
Você lê a linha 40 e precisa subir até a linha 12 pra lembrar o que tem dentro de $result. Aí desce, lê mais três linhas, e esquece de novo.
O código não tá complexo. Ele tá anônimo. E anonimato custa memória de trabalho, que é justamente o recurso mais escasso de quem lê código.
O crime na cena
public function processar(array $data): array
{
$result = [];
$temp = 0;
foreach ($data as $item) {
$d = $item['discount'] ?? 0;
$v = $item['price'] * $item['qty'];
$t = $v - ($v * $d / 100);
$temp += $t;
$result[] = [
'name' => $item['name'],
'total' => $t,
];
}
$info = ['items' => $result, 'sum' => $temp];
return $info;
}
Cinco letras soltas ($d, $v, $t) e três nomes genéricos ($data, $result, $temp, $info) num método de quinze linhas. Pra entender que $t é o total do item com desconto aplicado, você precisa executar o código na cabeça.
E o pior detalhe: $data aqui não é data (calendário) nem dado específico. É "coisas". É o equivalente a nomear uma pasta de "arquivos".
O mesmo método, com nome nas coisas
public function calcularCarrinho(array $itensDoCarrinho): array
{
$itensCalculados = [];
$totalDoCarrinho = 0;
foreach ($itensDoCarrinho as $item) {
$percentualDesconto = $item['discount'] ?? 0;
$subtotal = $item['price'] * $item['qty'];
$totalDoItem = $subtotal - ($subtotal * $percentualDesconto / 100);
$totalDoCarrinho += $totalDoItem;
$itensCalculados[] = [
'name' => $item['name'],
'total' => $totalDoItem,
];
}
return [
'items' => $itensCalculados,
'sum' => $totalDoCarrinho,
];
}
Mesma lógica. Zero comentário adicionado. E agora dá pra ler de cima pra baixo sem parar pra decifrar nada.
Repara que eu também matei o $info do final. Ele existia só pra guardar o retorno por uma linha — variável que só serve de escada pro return geralmente pode sumir.
Sete regras que resolvem 90% dos casos
1. O nome diz o conteúdo, não o tipo. $usuariosArray não ajuda — o PHP já sabe que é array. $usuariosInadimplentes ajuda.
2. Booleano começa com verbo de estado. $ativo é ambíguo (é o objeto ativo? é a flag?). $estaAtivo, $temEstoque, $podeEditar se leem como pergunta com resposta sim/não.
3. Coleção no plural, item no singular. foreach ($pedidos as $pedido). Parece óbvio, mas foreach ($pedido as $p) aparece muito.
4. Abreviação só se for universal. $id, $url, $html tudo bem. $qtdItPed não é economia, é criptografia.
5. Nome curto pra vida curta. Numa closure de uma linha, fn ($u) => $u->email é perfeitamente legível. Numa variável que vive quarenta linhas, o nome precisa se sustentar sozinho.
6. Use a palavra que o negócio usa. Se o pessoal do financeiro fala "inadimplente", a variável se chama $clientesInadimplentes — não $clientesComProblema. Isso encurta reunião.
7. Não nomeie pelo "como", nomeie pelo "o quê". $listaOrdenadaPorDataDesc envelhece na primeira mudança de ordenação. $ultimosPedidos sobrevive.
O nome que mente: pior que o nome ruim
$temp é preguiça, mas pelo menos é honesto: avisa que não vai te ajudar.
O problema sério é o nome que promete uma coisa e faz outra:
// diz que só busca. na verdade cria se não existir e ainda dispara e-mail. 😬
public function getUsuario(string $email): User
{
$usuario = User::firstOrCreate(['email' => $email]);
Mail::to($usuario)->send(new BoasVindas());
return $usuario;
}
Quem lê getUsuario() numa outra classe acha que é operação inofensiva de leitura. Chama dentro de um loop pra montar um relatório. E manda quatrocentos e-mails de boas-vindas pra base inteira.
Com $total acontece a mesma coisa: quem lê assume "valor final". Se aquele $total é antes do frete e do imposto, o nome certo é $subtotal. Um dia alguém vai somar duas vezes.
Nome ruim atrasa a leitura. Nome mentiroso causa bug.
A pegadinha: português, inglês ou os dois?
Aqui vem a parte que sempre gera discussão — e é discussão legítima.
Meu jeito: estrutura do framework em inglês, domínio na língua do negócio. Então public function store(), $request, User::create() ficam em inglês. Mas $clientesInadimplentes, NotaFiscal, calcularComissao() ficam em português, porque é assim que o time e o cliente falam.
O que eu evito com força é a mistura dentro do mesmo conceito: $userInadimplente, getClienteData(), NotaFiscalRepository::findByCliente(). Isso não é bilíngue, é confuso.
Se o time todo escreve em inglês e é consistente, ótimo, funciona também. O pecado mesmo é não ter combinado nada e cada arquivo seguir uma escola.
Bônus: quando o nome não sai
Aquele momento em que você fica cinco minutos travado tentando nomear um método é informação valiosa, não falta de vocabulário.
Se o nome honesto seria processarEValidarEEnviar(), o problema não é o nome. É que o método faz três coisas. Dificuldade de nomear quase sempre é sintoma de responsabilidade demais num lugar só.
Quebra em três, e os nomes aparecem sozinhos.
Antes de você fechar a aba
Nome de variável é o único tipo de documentação que nunca fica desatualizado, porque ele vive dentro do código. Comentário mente com o tempo. README envelhece. O nome, você é obrigado a manter.
E não custa nada. Não é refatoração de arquitetura, não precisa de aprovação, não entra em sprint. É F2 no editor e cinco segundos de atenção na hora de escrever.
Agora eu quero saber: qual o pior nome de variável que você já encontrou em produção? Aceito $xpto, $aux2, $naoMexeAqui e similares. Conta nos comentários que eu começo — já vi um $listaFinal2Corrigida em código rodando com cliente pagando. 😅
