Por que seu código sempre fica bagunçado quando você para de dar nomes sérios para as coisas
Eu passei os primeiros três anos da minha carreira escrevendo variáveis chamadas a, temp e resultado. Achava que era produtividade. Na verdade era preguiça com consequências. O problema não é que esses nomes são feios. O problema é que todo sistema cresce, e quando você precisa voltar ao que escreveu há seis meses para dar um conserto, não tem como lembrar o que aquela variável supostamente representava. O princípio de todas as coisas tem nome não é filosofia barata. É uma prática de engenharia que diz: se algo existe no seu domínio, ele merece um rótulo que comunique intenção, não apenas forma.
A regra que ninguém te ensina sobre naming
A maioria dos devs pensa que nomear bem é evitar nomes genéricos. Isso é metade da equação. A outra metade, e a mais difícil, é escolher o nível certo de granularidade. Eu vi times inteiros travados por causa de nomes excessivamente detalhados. Uma função chamada calcularDescontoAplicavelParaUsuarioComPlanoAtivoEMaiorQue18Anos não é melhor do que aplicarDesconto. O primeiro grita que quem escreveu estava preocupado em ser explícito. O segundo já é explícito o suficiente porque o corpo da função cuida do resto. O equilíbrio certo é isso: o nome deve dizer o quê, não como. Quando você começa a descrever o mecanismo no nome da coisa, seu código fica frágil. Se a implementação muda, o nome vira mentira. E uma mentira no nome é pior que um nome vago, porque cria confiança falsa.
Como aplicar na prática sem virar perfeccionista
Não existe fórmula. Existe prática repetida. O que funciona para mim é simplesmente ler o nome em voz alta dentro do contexto onde ele aparece. Se soa estranho, está ruim. Se soa natural, provavelmente está bom. Um problema concreto que eu encontrei recentemente: estava revisando um script de migração de banco onde existia uma variável chamada dados_para_filtrar. Durante três horas eu tentei entender o que aquele dado representava, de onde vinha e para onde ia. O nome não mentia, só era inútil. A solução foi renomear para registros_inativos_para_cleanup, que já eliminava metade da ambiguidade. Não foi genial. Foi só honestidade.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Outro pitfall comum é o time todo adotar nomenclatura em inglês sem motivo real. Se sua equipe é majoritariamente brasileira e todos leem o código diariamente, usuarios_ativos não é pior que active_users. A escolha de idioma é secundária. A escolha de ser claro é que importa. Inconsistência é o inimigo, não o idioma em si.
Onde esse princípio falha
Nomear tudo bem não resolve código mal estruturado. Eu já vi pessoas gastarem meia hora escolhendo o nome perfeito de uma variável que deveria ter sido eliminada. Isso é perda de tempo disfarçada de qualidade. Às vezes a resposta certa não é um bom nome, é não existir aquela abstração no seu código. Também não adianta nomear coisas que não têm existência real no domínio. Variáveis temporárias de loops, counters genéricos, flags booleanas sem contexto claro — Forçar que tudo tenha nome sofisticado gera ruído. Às vezes i ou count é exatamente o nome certo porque o contexto já deixa tudo óbvio.
O que eu faria diferente se começasse hoje
Eu começaria com uma coisa simples: qualquer nome que você precisar de um comentário para explicar, provavelmente precisa de um novo nome, não de um comentário. Comentários explicam porquês. Nomes explicam o quê. Quando você consegue transformar a explicação do comentário no próprio nome da variável ou função, seu código fica legível sem precisar de documentação adicional. Segundo ponto: nomes devem sobreviver a refatorações. Se o nome da função muda toda vez que você mexe na implementação, o problema não é o nome. O problema é que você está misturando duas responsabilidades numa só coisa. Separe. Nomeie cada parte separadamente. Aí sim o nome vai fazer sentido.
E sobre todas as coisas tem nome: isso não significa que tudo precisa de um nome longo ou elaborado. Significa que cada coisa que entra no seu sistema carrega uma responsabilidade clara, e essa responsabilidade deve ser comunicada pelo rótulo que você escolhe. Se você não consegue dar um nome razoável para algo, talvez esse algo não deva existir como entidade separada. O melhor teste que eu encontrei é colocar seu código na frente de alguém que não escreveu e ver se a primeira leitura já entrega o que está acontecendo. Se entregar, seu naming está bom. Se a pessoa precisar reler três vezes, volte e pense nos nomes de novo.
