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

A nomenclatura é uma das partes mais importantes e desafiadoras na escrita de código limpo, mantível e escalável. Um nome de variável bem pensado, por exemplo, pode funcionar como código autoexplicativo, poupando 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 classe, variáveis e funções com exemplos e melhores práticas.

Por Que a Nomenclatura é Importante?

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

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

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

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

Diferentes Estilos de Convenção de Nomenclatura

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

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

camelCase é amplamente usado 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 futuros desenvolvedores. Aqui está uma tabela de resumo rápido de algumas convenções de nomenclatura populares juntamente com seus casos de uso e exemplos:

Como Escolher o Estilo Certo

1. Específico da Linguagem: Siga as convenções de 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 Projeto: A consistência é fundamental. Utilize o estilo acordado para sua equipe/projeto.

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

Diretrizes Gerais de Nomenclatura

Antes de entrar 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. Avoidar abreviações criptográficas 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. Evite palavras-chave reservadas ou nomes confusos:

    // Ruim
    let let = 5;
   
    // Bom
    let nomeDaVariavel = 5;
   

Agora que abordamos o básico, vamos explorar algumas convenções de nomenclatura úteis.

Como Criar Bons Nomes de Classe

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

1. Use Nomes Descritivos

Nomes de classe 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)

BEM é uma convenção popular para escrever CSS escalável e manutenível. Ela 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

As variáveis guardam 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áximo, mínimo, total

• Arrays: Use formas no plural (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ções

Funções executam 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 para a ação, 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 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 contexto da programação:

1. Ele Representa o Propósito?

Os nomes orientados por objetivos 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 a necessidade de ler comentários adicionais ou documentação.

Como avaliar:

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

Exemplo:

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

2. É Suficientemente Específico?

O nome deve ser suficientemente específico para refletir o papel exato da entidade no seu código. Nomes excessivamente genéricos como data ou temp podem causar confusão porque não oferecem contexto suficiente.

Como avaliar:

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

Exemplo:

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

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

A 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:

Pergunta: “Este nome está em conformidade com as convenções de nomenclatura usadas no restante do projeto?” Siga as diretrizes do projeto, tais 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. Evita Ambiguidade?

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

Como Avaliar:

Pergunte: “Alguém não familiarizado com o código pode interpretar erroneamente para o que se refere este 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, facilidade de leitura e pronúncia pode melhorar a legibilidade e a manutenibilidade geral do seu código.

Como Avaliar:

Pergunte: “Este nome é fácil de ler em voz alta e eu consigo entendê-lo à primeira vista?”

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

Exemplo:

• maxRetries é melhor do que maximumNumberOfAttemptsToReconnect.

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á são claras a partir do contexto ao redor?”

Exemplo:

• Se você tem uma classe chamada User, nomear um método userGetData() é redundante. Em vez disso, use getData().

7. É Autoexplicativo?

Os melhores nomes se documentam sozinhos. 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 precisar de um comentário para explicar o que faz?”

Exemplo:

• A função calculateTotalPrice é autoexplicativa, 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 adequar ao contexto do seu projeto e seu domínio. Por exemplo, as convenções de nomenclatura para um aplicativo web podem ser diferentes das de um aplicativo móvel ou de um modelo de aprendizado de máquina.

Como Avaliar:

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

Se você está 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:

• Em um 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 mudanças futuras sem exigir refatoração.

Como Avaliar:

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

Exemplo:

• userInfo pode se tornar obsoleto 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 Diretamente?

Números mágicos (números com significado não claro) 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 MAX_FILE_SIZE para explicar o significado por trás do número.

Exemplos Práticos

Exemplo de CSS

O exemplo de CSS a seguir 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 estilos:

<!-- 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 de navegação principal.

• 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.
  Esta abordagem 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. O uso do prefixo is ajuda a identificá-la como um booleano.

  • 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 os detalhes do usuário. O parâmetro userId é descritivo e evita ambiguidades.

  • calculateTotalPrice(cartItems): O nome da função declara explicitamente a ação realizada. O parâmetro cartItems é contextualmente relevante para o domínio de comércio eletrônico.

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 manutenibilidade do seu código.

Tente seguir esses 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.

Essas e outras dicas que discutimos aqui farão com que seu código seja um prazer de trabalhar, quer você o revise meses depois ou colabore com uma equipe. Comece a aplicar essas dicas hoje e veja a qualidade do seu código decolar.