Pare de chamar variável de $data, $info e $temp

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. 😅

---