Como Escrever Melhores Nomes para suas Variáveis, Funções e Classes – Com Exemplos

Nomear é uma das partes mais importantes e desafiadoras de escrever código limpo, manutenível e escalável. Um nome de variável bem pensado, por exemplo, pode atuar como código auto-documentado, economizando tempo e esforço na compreensão da lógica. Mas nomes mal escolhidos, por outro lado, podem levar à confusão e bugs.

Este artigo servirá como um guia abrangente sobre como criar nomes significativos para nomes de classes, variáveis e funções, com exemplos e melhores práticas.

Por que a Nomeação é Importante?

• Legibilidade: Bons nomes tornam seu código intuitivo e reduzem a curva de aprendizado para os outros.

• Manutenibilidade: É mais fácil refatorar ou depurar código bem nomeado.

• Colaboração: Nomes claros melhoram a comunicação e a produtividade da equipe.

• Escalabilidade: Nomes significativos ajudam a manter grandes projetos gerenciáveis.

Diferentes Estilos de Convenção de Nomeação

Diferentes estilos de convenção de nomeação são cruciais para melhorar a legibilidade e a manutenibilidade do código em várias linguagens de programação.

Estilos como camelCase, PascalCase, snake_case e kebab-case são ajustados a contextos e práticas específicas.

camelCase é amplamente utilizado para variáveis e funções, enquanto PascalCase é preferido para classes. snake_case é um favorito em Python pela sua clareza, e kebab-case domina o CSS para estilização de elementos HTML.

Cada estilo garante consistência, tornando o código intuitivo para equipes e desenvolvedores futuros. Aqui está uma tabela rápida resumindo algumas convenções de nomenclatura populares, junto com seus casos de uso e exemplos:

Como Escolher o Estilo Certo

1. Específico da Linguagem: Siga as convenções da sua linguagem de programação ou framework. Por exemplo:

   • JavaScript: camelCase para variáveis e funções, PascalCase para componentes.

   • Python: snake_case para variáveis e funções.

   • CSS/HTML: kebab-case para nomes de classes e IDs.

2. Padrões da Equipe ou do Projeto: Consistência é fundamental. Use o estilo acordado para sua equipe/projeto.

3. Específico para o Propósito: Utilize estilos de nomenclatura que melhor representem a entidade sendo nomeada (por exemplo, constantes em SCREAMING_SNAKE_CASE).

Diretrizes Gerais de Nomenclatura

Antes de mergulhar em convenções de nomenclatura específicas para nomes de classes, variáveis e funções, vamos explorar alguns princípios universais:

1. Seja descritivo e conciso: Os nomes devem transmitir o propósito ou função da variável/função/etc:

    // Ruim
    let x = 10;
   
    // Bom
    let maxUsuariosPermitidos = 10;
   

2. Avoid abreviações crípticas que podem ser difíceis para outros desenvolvedores entenderem (ou até mesmo para o seu futuro eu):

    // Ruim
    let usrNm = "John";
   
    // Bom
    let userName = "John";
   

3. Utilize convenções de nomenclatura consistentes: Escolha um estilo de nomenclatura (camelCase, PascalCase, kebab-case, snake_case) e mantenha-o ao longo do seu projeto.

4. Avoid palavras-chave reservadas ou nomes confusos:

    // Ruim
    let let = 5;
   
    // Bom
    let variableName = 5;
   

Certo, agora que cobrimos o básico, vamos aprofundar um pouco mais em algumas convenções de nomenclatura úteis.

Como Criar Bons Nomes de Classes

Nomes de classes definem o comportamento visual ou estrutural dos elementos em sua aplicação. Escrever nomes de classes claros garante que seu HTML e CSS sejam fáceis de entender e manter.

1. Use Nomes Descritivos

Nomes de classes devem descrever o propósito do elemento, não sua aparência.

<!-- Ruim -->
<div class="red-button"></div>

<!-- Bom -->
<div class="primary-button"></div>

2. Siga a Metodologia BEM (Bloco-Elemento-Modificador)

O BEM é uma convenção popular para escrever CSS escalável e de fácil manutenção. Ele separa os componentes em:

• Bloco: Representa o componente (por exemplo, card).

• Elemento: Representa elementos filhos do bloco (por exemplo, card__title).

• Modificador: Representa variações do bloco ou elemento (por exemplo, card__title--highlighted).

Exemplo:

<div class="card">
  <h1 class="card__title card__title--highlighted">Welcome</h1>
  <p class="card__description">This is a card component.</p>
</div>

3. Use kebab-case

Nomes de classes CSS são tradicionalmente escritos em kebab-case para melhor legibilidade.

<!-- Ruim -->
<div class="primaryButton"></div>

<!-- Bom -->
<div class="primary-button"></div>

Como Criar Bons Nomes de Variáveis

Variáveis armazenam dados e devem ter nomes significativos que descrevam o que representam.

1. Use Substantivos para Variáveis

Variáveis são tipicamente substantivos porque representam entidades ou dados.

// Ruim
let a = "John";

// Bom
let userName = "John";

2. Use Prefixos para Adicionar Contexto

Adicionar prefixos ajuda a esclarecer o tipo ou propósito de uma variável:

• Boolean: é, tem, pode

• Números: máx, mín, total

• Arrays: Use formas plurais (por exemplo, usuários, itens).

Exemplo:

let isUserLoggedIn = true;
const maxUploadLimit = 5; // MB
const usersList = ["John", "Jane"];

3. Evite Nomes Genéricos

Evite nomes como dados, valor ou item a menos que sejam necessários.

// Ruim
let data = 42;

// Bom
let userAge = 42;

Como Criar Bons Nomes de Função

Funções realizam ações, então seus nomes devem refletir a operação ou processo que executam.

1. Use Verbos para Funções

Funções são orientadas a ações, então seus nomes devem começar com um verbo:

// Ruim
function userData() {
  // ...
}

// Bom
function fetchUserData() {
  // ...
}

2. Seja Específico Sobre a Funcionalidade

Os nomes das funções devem indicar o que elas fazem.

// Ruim
function handle() {
  // ...
}

// Bom
function handleFormSubmit() {
  // ...
}

3. Use Prefixos para Intenção

• Para manipuladores de eventos: handle, on

• Para utilitários: calculate, convert, format

• Para operações de busca: fetch, get, load

• Para setters e getters: set, get

Exemplo:

function handleButtonClick() {
  console.log("Button clicked!");
}

function calculateDiscount(price, discountPercentage) {
  return price * (discountPercentage / 100);
}

Como Saber se um Nome é Bom para uma Variável, Função ou Classe

Para entender se um nome é bom para uma variável, função ou classe, é importante avaliá-lo usando vários princípios-chave. Aqui está um guia para ajudá-lo a decidir se um nome é apropriado e significativo no seu contexto de programação:

1. Ele Representa o Propósito?

Nomes orientados por propósito são a característica mais importante de um bom nome. Um nome deve imediatamente dizer o que a variável, função ou classe representa ou faz sem precisar ler comentários adicionais ou documentação.

Como avaliar:

Pergunte a si mesmo: “Quando leio este nome, consigo entender imediatamente seu propósito?”

Exemplo:

• idadeDoUsuario é melhor do que a porque idadeDoUsuario diz o que a variável representa, enquanto a é muito ambíguo.

2. É Específico Suficiente?

O nome deve ser suficientemente específico para refletir o papel exato da entidade em seu código. Nomes excessivamente genéricos como dados ou temp podem ser confusos porque não fornecem contexto suficiente.

Como avaliar:

Pergunte: “Este nome é específico para o que esta variável, função ou classe representa em minha aplicação?”

Exemplo:

• calcularValorDoImposto() é melhor do que calcular() porque é claro o que a função está calculando.

3. Segue uma Convenção de Nomenclatura Consistente?

Consistência nas convenções de nomenclatura é vital. Quando todos os membros da equipe seguem as mesmas convenções, o código é mais fácil de entender e navegar.

Como avaliar:

Pergunte: “Este nome está de acordo com as convenções de nomenclatura usadas no restante do projeto?” Siga as diretrizes do projeto, como:

• camelCase para variáveis e funções (por exemplo, userAge)

• PascalCase para classes (por exemplo, UserProfile)

• UPPERCASE_SNAKE_CASE para constantes (por exemplo, MAX_USERS)

Exemplo:

• Se sua equipe segue camelCase, userData é melhor do que UserData.

4. Isso Evita Ambiguidade?

Um bom nome elimina ambiguidade. Não deve estar aberto a múltiplas interpretações. Se puder significar coisas diferentes em diferentes contextos, isso levará à confusão.

Como Avaliar:

Pergunte: “Alguém não familiarizado com a base de código poderia interpretar erroneamente a que se refere esse nome?”

Exemplo:

• Em vez de nomear um booleano isValid, use isUserLoggedIn ou isEmailVerified para tornar mais claro o que está sendo verificado.

5. É Fácil de Ler e Pronunciar?

Embora não seja estritamente necessário, a facilidade de leitura e pronúncia pode melhorar a legibilidade geral e a manutenibilidade do seu código.

Como Avaliar:

Pergunte: “Este nome é fácil de ler em voz alta e consigo entendê-lo num relance?”

Avoid nomes longos e use abreviações comuns apenas quando amplamente aceitas.

Exemplo:

• maxRetries é melhor do que númeroMáximoDeTentativasDeReconexão.

6. Evita Redundância?

Evite redundância nos nomes. Não repita informações que já estão implícitas ou descritas pelo contexto.

Como Avaliar:

Pergunte: “Estou repetindo informações que já estão claras no contexto circundante?”

Exemplo:

• Se você tem uma classe chamada Usuário, nomear um método usuárioObterDados() é redundante. Em vez disso, use obterDados().

7. É Autoexplicativo?

Os melhores nomes se autoexplicam. Bons nomes reduzem a necessidade de comentários ou explicações adicionais.

Como Avaliar:

Pergunte: “Este nome descreve completamente a variável, função ou classe sem exigir um comentário para explicar o que faz?”

Exemplo:

• calculateTotalPrice é autoexplicativo, então não há necessidade de um comentário adicional como “Esta função calcula o preço total após o desconto.”

8. É Contextual e Relevante para o Domínio?

O nome deve se encaixar no contexto do seu projeto e seu domínio. Por exemplo, as convenções de nomenclatura para uma aplicação web podem diferir daquelas para um aplicativo móvel ou um modelo de aprendizado de máquina.

Como Avaliar:

Pergunte: “Este nome está alinhado com o domínio e o contexto do meu projeto?”

Se você estiver trabalhando em um domínio específico (por exemplo, finanças, saúde, jogos), use termos específicos do domínio que sejam facilmente reconhecíveis.

Exemplo:

• No aplicativo de jogos, healthPoints é mais apropriado do que hp, pois reflete seu significado.

9. É à Prova de Futuro?

Pense em como seu código irá evoluir. Os nomes devem ser flexíveis o suficiente para acomodar futuras mudanças sem exigir refatoração.

Como Avaliar:

Pergunte: “Este nome ainda fará sentido se a funcionalidade mudar ou o projeto crescer?”

Exemplo:

• userInfo pode se tornar desatualizado se a estrutura de dados mudar. É melhor usar userProfile se você espera que mais campos sejam adicionados.

10. Evita Números Mágicos e Valores Codificados?

Números mágicos (números com significado obscuro) devem ser evitados em favor de constantes nomeadas.

Como Avaliar:

Pergunte: “Este nome representa uma constante significativa ou é apenas um número bruto?”

Exemplo:

• Em vez de usar 1000, use uma constante como TAMANHO_MAXIMO_ARQUIVO para explicar o significado por trás do número.

Exemplos Práticos

Exemplo de CSS

O seguinte exemplo de CSS demonstra como aplicar as convenções de nomenclatura BEM (Bloco-Elemento-Modificador) para manter uma hierarquia de classes estruturada e escalável em sua folha de estilo:

<!-- HTML -->
<div class="navbar">
  <ul class="navbar__list">
    <li class="navbar__item navbar__item--active">Home</li>
    <li class="navbar__item">About</li>
    <li class="navbar__item">Contact</li>
  </ul>
</div>

/* CSS */
.navbar {
  background-color: #333;
  padding: 10px;
}

.navbar__list {
  list-style: none;
}

.navbar__item {
  display: inline-block;
  padding: 10px;
}

.navbar__item--active {
  color: orange;
}

Aqui está o que está acontecendo neste código:

• Nomenclatura BEM: navbar é o Bloco, representando o componente principal de navegação.

• navbar__list é o Elemento, um filho do bloco, representando a lista de itens de navegação.

• navbar__item é outro Elemento representando itens individuais da lista.

• navbar__item--active é um Modificador usado para destacar o item de menu ativo.
  Esse enfoque facilita a compreensão das relações e funções dentro do HTML e CSS, apoiando estilos modulares e reutilizáveis.

Exemplo de JavaScript

Este exemplo de JavaScript mostra como usar convenções de nomenclatura significativas e consistentes para variáveis e funções, tornando o código autoexplicativo:

// Variáveis
let isUserLoggedIn = false;
const maxAllowedItems = 10;

// Funções
function fetchUserDetails(userId) {
  // Obter dados do usuário da API
}

function calculateTotalPrice(cartItems) {
  return cartItems.reduce((total, item) => total + item.price, 0);
}

Aqui está o que está acontecendo no código:

• Variáveis:

  • isUserLoggedIn: Uma variável booleana nomeada claramente para indicar seu propósito. Adicionar o prefixo is ajuda a identificá-la como booleana.

  • maxAllowedItems: Uma constante com um prefixo max em maiúsculas mostra que é um limite, deixando sua intenção clara.

• Funções:

  • fetchUserDetails(userId): O nome reflete o propósito da função, que é recuperar detalhes do usuário. O parâmetro userId é descritivo e evita ambiguidade.

  • calculateTotalPrice(cartItems): O nome da função declara explicitamente a ação realizada. O parâmetro cartItems é contextualmente relevante para o domínio do e-commerce.

Por Que É Bom: Essas convenções garantem que o código seja legível e intuitivo, reduzindo a carga cognitiva para outros desenvolvedores que trabalham no mesmo projeto.

Conclusão

Nomear de forma significativa é tanto uma convenção importante quanto uma forma de arte que impacta significativamente a legibilidade e a manutenção do seu código.

Tente seguir estes princípios básicos:

• Use nomes descritivos e concisos.

• Adira a convenções consistentes como BEM para nomes de classes e camelCase para variáveis e funções.

• Use prefixos para adicionar contexto e clareza.

Estas e outras dicas discutidas aqui farão com que seu código seja uma alegria para trabalhar, seja ao revisitá-lo meses depois ou ao colaborar com uma equipe. Comece a aplicar essas dicas hoje e veja a qualidade do seu código decolar.