Nomenclatura de variáveis: a arte de nomear coisas de forma clara

1. Por que nomes de variáveis importam?

O custo da má legibilidade em código é frequentemente subestimado. Estudos mostram que programadores passam cerca de 60% do tempo lendo código, não escrevendo. Cada nome mal escolhido gera um pequeno atrito mental que, acumulado, transforma-se em horas perdidas em revisões e debugging.

Nomes de variáveis funcionam como documentação viva. Um bom nome reduz drasticamente a necessidade de comentários explicativos. Considere:

// Ruim: requer comentário para explicar
let d = new Date(); // data atual
let t = d.getTime(); // timestamp
let r = t % 86400000; // resto do dia em ms

// Bom: autoexplicativo
let currentDate = new Date();
let currentTimestamp = currentDate.getTime();
let millisecondsSinceMidnight = currentTimestamp % 86400000;

A manutenibilidade sofre diretamente com nomes ruins. Cada variável mal nomeada contribui para a dívida técnica, tornando o sistema mais custoso de modificar e mais propenso a bugs.

2. Princípios fundamentais de nomenclatura

Clareza sobre brevidade é o princípio mais importante. Nomes descritivos são preferíveis a abreviações obscuras:

// Evite
let usrNm = "João";
let addr = "Rua A";
let ph = "11999999999";

// Prefira
let userName = "João";
let userAddress = "Rua A";
let userPhone = "11999999999";

Contexto e escopo definem o nível de detalhe necessário. Variáveis locais em funções curtas podem ser mais concisas do que variáveis globais ou de classe:

// Escopo local (função curta) - abreviação aceitável
function calculateArea(r) {
    return Math.PI * r * r;
}

// Escopo global - requer nome completo
const globalUserAuthenticationToken = "abc123";

Consistência no time exige um glossário compartilhado. Defina convenções para prefixos, sufixos e padrões de nomenclatura que todos sigam.

3. Boas práticas por tipo de dado

Booleanos devem usar prefixos que indiquem perguntas:

let isActive = true;
let hasPermission = false;
let shouldRetry = true;
let canEdit = false;
let isLoaded = true;

Números e contadores precisam ter a unidade embutida no nome:

let timeoutInSeconds = 30;
let maxRetries = 3;
let fileSizeInMegabytes = 2.5;
let temperatureInCelsius = 25;
let priceInReais = 49.90;

Coleções e arrays devem ser claramente pluralizados:

let users = ["Ana", "João", "Maria"];
let itemList = [1, 2, 3];
let nameSet = new Set(["Ana", "João"]);
let userMap = new Map();
let activeUserIds = [101, 102, 103];

4. Evitando armadilhas comuns

Abreviações e siglas sem significado são particularmente prejudiciais:

// Evite
let tmp = "valor temporário";
let data = { id: 1 };
let obj = { nome: "João" };

// Prefira
let temporaryValue = "valor temporário";
let userData = { id: 1 };
let person = { nome: "João" };

Nomes genéricos e sobrecarga semântica criam confusão:

// Evite
let manager = new UserManager();
let handler = new RequestHandler();
let info = { name: "João", age: 30 };

// Prefira
let userManager = new UserManager();
let requestHandler = new RequestHandler();
let userInfo = { name: "João", age: 30 };

Ruído visual com redundâncias desnecessárias:

// Evite
let userObject = { name: "João" };
let stringName = "João";
let numberAge = 30;

// Prefira
let user = { name: "João" };
let name = "João";
let age = 30;

5. Nomenclatura em diferentes paradigmas

Programação funcional favorece imutabilidade e verbos no particípio:

let filteredUsers = users.filter(user => user.isActive);
let computedTotal = items.reduce((sum, item) => sum + item.price, 0);
let sortedNames = names.sort();
let mappedIds = users.map(user => user.id);

Programação orientada a objetos exige nomes que reflitam o domínio:

class BankAccount {
    constructor(ownerName, initialBalance) {
        this.ownerName = ownerName;
        this.balance = initialBalance;
        this.transactionHistory = [];
    }

    deposit(amount) {
        this.balance += amount;
        this.transactionHistory.push({ type: "deposit", amount });
    }

    withdraw(amount) {
        if (this.balance >= amount) {
            this.balance -= amount;
            this.transactionHistory.push({ type: "withdrawal", amount });
        }
    }
}

Linguagens com tipagem dinâmica exigem nomes mais descritivos, já que não há tipo explícito:

// JavaScript (tipagem dinâmica)
let userAge = 30; // necessário incluir contexto no nome
let isUserActive = true;

// TypeScript (tipagem estática)
let age: number = 30; // tipo já informa o contexto
let isActive: boolean = true;

6. Ferramentas e técnicas para melhorar nomes

Code review focado em nomenclatura deve incluir perguntas guia:
- O nome reflete o propósito da variável?
- Um novo membro do time entenderia este nome?
- Existe ambiguidade potencial?

Renomeação incremental com IDEs modernas permite refatoração segura:

// Antes da refatoração
let x = getUserData();

// Após renomeação segura (IDE renomeia todas as referências)
let userProfile = getUserData();

Uso de linters como ESLint com regras de nomenclatura:

// ESLint detecta nomes inadequados
// .eslintrc.json
{
    "rules": {
        "id-length": ["error", { "min": 2 }],
        "camelcase": "error"
    }
}

7. Exemplos práticos: do ruim ao bom

Antes e depois de refatoração:

// Código original (ruim)
function calc(a, b, c) {
    let x = a * b;
    let y = x + c;
    return y / 2;
}

// Código refatorado (bom)
function calculateAverage(grade1, grade2, bonus) {
    let gradesSum = grade1 * grade2;
    let totalWithBonus = gradesSum + bonus;
    return totalWithBonus / 2;
}

Casos de fronteira onde quebrar a regra é aceitável:

// Loops com contadores: i, j, k são aceitáveis
for (let i = 0; i < users.length; i++) {
    for (let j = 0; j < users[i].items.length; j++) {
        processItem(users[i].items[j]);
    }
}

// Matemática: x, y, z são aceitáveis em contextos matemáticos
function calculateDistance(x1, y1, x2, y2) {
    return Math.sqrt((x2 - x1) ** 2 + (y2 - y1) ** 2);
}

Estratégia para limpeza progressiva de código legado:

// Passo 1: Identificar nomes críticos
let d = getData(); // nome genérico

// Passo 2: Renomear com segurança
let dashboardData = getData(); // mais específico

// Passo 3: Verificar todas as referências
console.log(dashboardData); // agora claro

A arte de nomear variáveis é uma habilidade que se desenvolve com prática e revisão constante. Lembre-se: código é escrito para humanos lerem, e máquinas apenas executarem. Nomes claros são o maior presente que você pode dar ao seu time e ao seu futuro eu.

Referências