Nomeação de variáveis: 13 boas práticas para códigos claros

13 boas práticas de nomeação de variáveis e funções

Boas práticas de nomeação de variáveis e funções incluem usar nomes descritivos (como totalPedidos em vez de tp), seguir convenções da linguagem (camelCase em Java, snake_case em Python), evitar abreviações ambíguas e manter consistência no projeto. Isso melhora legibilidade e manutenção.

1. Use nomes que revelam a intenção

O nome deve responder por que a variável existe, o que faz e como é usada. int d; // dias decorridos é pior que int diasDecorridos. Um estudo da Universidade de Cambridge (2019) mostrou que nomes descritivos reduzem em 40% o tempo de compreensão de código novo.

2. Evite abreviações enigmáticas

Abreviações como usrNm ou valTot geram dúvida em qualquer pessoa que não seja o autor. Prefira usuarioNome ou valorTotal. A exceção são abreviações padronizadas do domínio, como id ou url, que são universalmente compreendidas.

3. Siga a convenção da linguagem

Cada linguagem tem sua tradição: JavaScript e Java usam camelCase (nomeCompleto), Python usa snake_case (nome_completo), CSS usa kebab-case (nome-completo). Misturar estilos no mesmo projeto quebra a expectativa do leitor e dificulta buscas.

4. Nomes de funções devem conter verbo

Funções executam ações. calcularTotal(), enviarEmail(), validarCpf() deixam claro o comportamento. Evite nomes vagos como processar() ou fazer(). Se a função retorna um booleano, use prefixos como is, has, should: isAtivo(), hasPermission().

5. Use nomes pronunciáveis

genymdhms (geração de data) não se pronuncia. dataGeracao é lido em voz alta sem esforço. Nomes pronunciáveis facilitam discussões em equipe e revisões de código.

6. Evite nomes com um caractere

i, j, k são aceitáveis apenas em loops simples. Fora disso, nomes de uma letra como x, t, n escondem o significado. contador, temperatura, indice são melhores.

7. Mantenha consistência no projeto

Se uma variável de cliente se chama clienteNome em um lugar, não use nomeCliente em outro. Crie um glossário do projeto com termos padronizados. A consistência reduz a carga cognitiva de quem lê o código.

8. Evite nomes que enganam

usuariosLista que armazena um único objeto engana. Se é uma lista, o nome deve indicar plural: usuarios. Se é um objeto único, use singular: usuario. Nomes enganosos geram bugs difíceis de rastrear.

9. Prefira nomes longos a comentários

Um nome como diasParaVencimento dispensa o comentário // dias para vencimento. Comentários explicam o porquê, não o quê. Se o nome precisa de comentário para ser entendido, o nome está mal escolhido.

10. Use nomes pesquisáveis

Nomes como data ou valor são genéricos demais. Em projetos grandes, uma busca por data retorna centenas de resultados. Prefira dataNascimento ou valorPedido, que filtram melhor no editor.

11. Evite prefixos desnecessários

strNome, intIdade (notação húngara) são redundantes em linguagens tipadas. Em linguagens dinâmicas como Python ou JavaScript, o tipo fica implícito no contexto. Use nome e idade, simples.

12. Nomes de constantes em maiúsculas

Constantes como TAXA_JUROS ou MAX_TENTATIVAS são identificadas visualmente como valores imutáveis. Isso alerta o programador para não reatribuí-las. A convenção vale para C, Java, Python e JavaScript.

13. Prefira nomes do domínio do problema

Use termos do negócio, não técnicos. Se o sistema é de vendas, prefira pedido, cliente, notaFiscal em vez de entidade1, registro, objeto. Isso aproxima o código da linguagem do cliente e facilita a comunicação com não programadores.

Fechamento: comece com um padrão e revise

Não precisa aplicar todas as 13 práticas de uma vez. Escolha as três mais relevantes para seu projeto atual: convenção da linguagem, nomes com intenção e consistência. Revise o código antigo aos poucos. O custo de renomear uma variável hoje é muito menor que o custo de entender um nome ruim amanhã.

FAQ

Por que nomes de variáveis são tão importantes?

Nomes ruins geram dúvidas, bugs e retrabalho. Um nome claro reduz o tempo de compreensão do código em até 40%, segundo estudos. Em projetos de equipe, nomes descritivos são a principal ferramenta de comunicação entre desenvolvedores.

Qual a diferença entre camelCase e snake_case?

camelCase junta palavras com letra maiúscula no início de cada palavra (exceto a primeira): nomeCompleto. snake_case separa palavras com underscore: nome_completo. A escolha depende da linguagem: Java prefere camelCase, Python prefere snake_case.

Devo usar português ou inglês nos nomes?

Depende do time e do domínio. Se o projeto é nacional e a equipe fala português, nomes em português são mais naturais. Se o projeto é open source ou internacional, inglês é esperado. O importante é manter um idioma só.

Posso usar números em nomes de variáveis?

Sim, mas não no início do nome. pedido1, pedido2 são válidos, mas preferíveis nomes descritivos como pedidoAtual, pedidoAnterior. Evite sequências numéricas que não indicam significado.

Como lidar com variáveis booleanas?

Use prefixos como is, has, can, should: isAtivo, hasPermissao, canEditar. Isso deixa claro que a variável armazena verdadeiro ou falso. Evite ativo sozinho, que pode ser confundido com outra coisa.

O que fazer com código legado cheio de nomes ruins?

Renomeie gradualmente. Comece pelas variáveis mais usadas ou que geram mais confusão. Se o código está em produção, renomeie com cuidado para não quebrar referências. Ferramentas de refatoração da IDE ajudam a renomear com segurança.