Nomeação de variáveis baseada no clean code

Clean Code é o conjunto de várias convenções de código que juntas criam um novo jeito de escrever seu código para que ele possa ser mais legível , manutenível, confiável e previsível promovendo eficiência e facilitando o trabalho em equipe.

Um dos vários princípios do clean code é a nomeação de variáveis com nomes que sejam auto descritíveis e auto explicativos para evitar ambiguidades e escrever códigos mais limpos, um grande autor  Zeno Rocha disse em seu livro 14 Habits of Highly Productive Developers  devemos sempre escrever um código que o nosso eu do futuro consiga entender mesmo depois de anos. Nomear variáveis com diminutivos ou abreviações pode levar a diferentes interpretações, especialmente entre desenvolvedores com diferentes níveis de envolvimento no projeto isso pode levar a problemas futuros.

É muito comum que a medida que o code base cresce e sua variável seja deixada de lado haja uma necessidade de revisita-la futuramente e uma escrita ruim dificultará o entendimento do seu código que ajudar.

exemplos de péssimas variáveis :

const date = new Date()
// Nome da varável é muito genêrica e não explica o que ela é

function getData(req, res) {}
// Nâo descreve bem o dado que ela está requisitando 

exemplos de boas variáveis :

const currentDate = new Date()
// Nome mais explicativo sobre o que ela é e menos genêrico

function getUserGithubCategory(req, res) {} 
// Descreve melhor o dado que a função está requisitando 

Ainda nessa mesma lógica de escrever nomes de variáveis significativos entramos em um outro ponto importante que seria na hora de escrever variáveis booleanas que seguem o mesmo sentido de escrita porém devemos usar uma outra regrinha acumulada a anterior.

Ela diz o seguinte, devemos escrever variáveis booleanas como se fossem algum tipo de pergunta que pode ser respondida com sim ou não, isso se dá devido que variáveis booleanas só podem receber true ( sim ) ou false ( não ) e uma pergunta ara dizer se estão ativas ou não ajuda na leitura de código.

exemplo sem a aplicação da regra :

const ticketPark = user.ticketPark 

if (!ticketPark ) {
  throw new Error('O Marcos não possui um bilhete para entrar no parque!')
}

exemplo com a aplicação da regra :

const hasUserTicket = user.hasTicket // o usuário tem o ticket ?

if (!hasUserTicket) { // se o usuário não tiver o ticket 
  throw new Error('O Marcos não possui um bilhete para entrar no parque!')
}

Concorda comigo que ao usar esse modelo de nomear as variáveis booleanas não deixa a leitura mais simples ao dizer que se o usuário tiver o ticket ele pode ir ao brinquedo do que mesmo só verificar se ticket do parque não é falso ? Usar esses tipos de pode realmente melhorar o entendimento do seu código por terceiros e ajudar para que evite ambiguidades também.

Por fim temos apenas mais uma regrinha simples que acompanha essas duas ultimas que além de escrever melhor seu código é usar variáveis para armazenar os “números mágicos” no seu código. Mais afinal o que são esses números mágicos no seu código ? Geralmente muitos programadores na hora de aplicar a regra de negócio em seus projetos utilizam vários números para realizar algumas operações no código e que por sua vez ficam jogados no código sem necessariamente ter alguma explicação do porque dele estar ali.

exemplo de um código cheio de números mágicos :

function calculateShippingCost(distance: number, weight: number): number {
    if (distance < 100) {
        return weight * 5; 
    } else if (distance < 500) {
        return weight * 10; 
    } else {
        return weight * 15; 
    }
}

const cost = calculateShippingCost(250, 20);
console.log(`Custo do frete: $${cost}`);

consegue entender para que serve o código?

Dificulta com esses números indescritíveis né ?

você já chegou a ouvir essa frase “não sei porque mais se remover aquilo o código quebra ” ? Ela representa bem o que eu quero dizer aqui, evite deixar esses números soltos e sem uma explicação do porque ele está ali caso não dê para deixar claro em uma variável faça um comentário simples afinal comentários nunca são demais para garantir que esse tipo de frase não possa existir em seu código.

Dá uma olhada como deveria ser escrito esse código :

// Constantes para faixas de distância
const SHORT_DISTANCE_THRESHOLD = 100;
const MEDIUM_DISTANCE_THRESHOLD = 500;

// Constantes para taxas de frete
const SHORT_DISTANCE_RATE = 5;  // $5 por kg
const MEDIUM_DISTANCE_RATE = 10; // $10 por kg
const LONG_DISTANCE_RATE = 15;  // $15 por kg

function calculateShippingCost(distance: number, weight: number): number {
    if (distance < SHORT_DISTANCE_THRESHOLD) {
        return weight * SHORT_DISTANCE_RATE;
    } else if (distance < MEDIUM_DISTANCE_THRESHOLD) {
        return weight * MEDIUM_DISTANCE_RATE;
    } else {
        return weight * LONG_DISTANCE_RATE;
    }
}

const cost = calculateShippingCost(250, 20);
console.log(`Custo do frete: $${cost}`);

Melhorou agora né?

Benefícios

Adotar práticas como nomear variáveis de forma clara, evitar números mágicos e seguir os princípios do Clean Code não apenas melhora a qualidade do seu código, mas também facilita a colaboração com outros desenvolvedores e a manutenção a longo prazo.

Lembre-se: escrever código limpo não é sobre alcançar a perfeição, mas sim sobre tornar o código mais acessível, compreensível e previsível para todos que o utilizarem, incluindo você no futuro.

Experimente aplicar essas regrinhas no seu próximo projeto e perceba a diferença! Compartilhe essas dicas com colegas ou na sua equipe para criar um ambiente de trabalho mais produtivo e eficiente. Afinal, um código bem escrito é o primeiro passo para construir software de alta qualidade.

Então, que tal começar hoje? Escreva códigos que você se orgulhará de ler no futuro!