Por que eu parei de dar nome para tudo
Eu passava umas duas horas por semana organizando pastas, variáveis e arquivos no projeto da empresa porque cada coisa precisava ter um nome que "fazesse sentido". A gente tinha uma convenção, um guia de estilo, uma página no Confluence. E ainda assim todo mundo nomeava as coisas de um jeito diferente. O que eu chamei de cliente_api, meu colega chamava de gateway_servico. Duas semanas de revisão de código pra descobrir que eram a mesma coisa. Aí eu li sobre o princípio de que todas as coisas tem nome como se fosse uma regra sagrada da organização do conhecimento. E resolvi testar do jeito mais burro possível: parei de tentar criar nomes perfeitos e comecei a usar nomes feios, mas consistentes, com um dicionário centralizado. O resultado não foi mágico, mas foi real.
O problema real que ninguém conta sobre nominação
O conceito é simples na teoria. Todo artefato — arquivo, variável, pasta, módulo — recebe um nome que descreve sua função no sistema. Na prática, o problema é que nomes são interpretações. Duas pessoas olhando pra mesma coisa vão escrever dois nomes diferentes porque veem funções diferentes. Eu já vi isso acontecer com um serviço de autenticação que um dev chamava de auth_provider e outro de identity_service. O código era idêntico. O GitHub blamava diferente. O que eu descobri foi que o esforço de nomear não é o problema. O problema é manter os nomes atualizados quando o sistema muda. Eu tive um projeto onde renomeamos trinta e sete arquivos em uma refatoração. Metade dos nomes novos ainda apareciam em documentação, scripts de deploy e mensagens de log. Levei três semanas pra resolver, e não porque era difícil — era chato, repetitivo, e ninguém queria fazer.
Como eu aplico na prática
Primeiro, eu crio um arquivo chamado NAMING.md na raiz do projeto. Não é um guia perfeito. É uma lista de decisões. Tipo: "serviços que falam com APIs externas vão ter _api no final". "Configurações de ambiente vão morar em config/". Quando alguém pergunta "como eu chamo isso?", a gente consulta o arquivo, não a intuição. Segundo, eu uso nomes feios durante o desenvolvimento. temp1, data_x, thing_handler. Isso acelera a escrita. Nada pior do que travar quinze minutos tentando escolher entre user_manager e user_service. Depois, na fase de refinamento, eu substituo pelo nome correto baseado no dicionário. É mais rápido porque o código já tá funcionando. Revisar um nome é trivial. Criar um código do zero sem saber o nome é perda de tempo.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Terceiro, eu não nomeio coisas que não existem ainda. Tem muita gente que cria pastas e arquivos só pra ter estrutura. Isso é armadilha. Eu vejo gente criando src/components/shared/ antes de ter qualquer componente compartilhado. Quando o componente finalmente aparece, o caminho já não faz mais sentido e todo mundo ignora a pasta. Naming sem conteúdo é só ruído.
Onde o princípio falha completamente
Em projetos muito dinâmicos, como um data pipeline que muda de fonte todo mês, nomear tudo gera mais trabalho do que valor. Eu tive um projeto de ETL onde as tabelas de entrada mudavam semanalmente. Criar nomes fixos pra cada uma era impossível. Aí eu mudei a estratégia: em vez de nomear as tabelas, nomeei os estágios do pipeline (ingest, transform, load) e deixei os dados com nomes brutos. Funcionou melhor porque o nome fixo era onde a estabilidade existia, não nos dados voláteis. Outro caso onde isso não funciona é em equipes grandes com mais de vinte pessoas contribuindo ao mesmo tempo. Um dicionário centralizado vira gargalo. Alguém precisa aprovar cada nome novo, e aí a coisa travam. Nesses cenários, eu recomendo dividir o projeto em subsistemas com donos definidos, onde cada dono tem autonomia pra nomear dentro do seu domínio. O dicionário só entra pra evitar colisões entre domínios.
O que eu ganharia se soubesse antes
Cinco horas por semana economizadas em revisão de código. Menos discussões em pull request sobre nomenclatura. Menos documentação desatualizada porque os nomes no código batiam com os nomes no texto. E mais importantly, menos ambiguidade quando alguém novo entrava no projeto e precisava entender onde algo estava. O princípio de que todas as coisas tem nome não é sobre perfeição. É sobre reduzir fricção. Um nome ruim é melhor que nenhum nome. Um nome consistente é melhor que um nome perfeito. E um nome que muda junto com o código é melhor que um nome bonito que ninguém atualiza.
Minha recomendação prática: comece pequeno. Pegue um único projeto, escreva cinco regras de nomenclatura no NAMING.md, e aplique por três meses. Se não fizer diferença,descarte. Se fizer, expanda. Não tente resolver isso pra toda a empresa de uma vez. Funciona por persuasão, não por decreto.
