Perché dovresti usare nomi di variabili descrittivi per scrivere codice auto-documentato

Regola
Usa nomi di variabili descrittivi.
Nomi di variabili molto brevi rendono il codice poco chiaro.

Linguaggi supportati: 45+

Introduzione

Nomi di variabili a lettera singola o criptici costringono chi legge a dedurre il significato dal contesto anziché comprendere il codice a colpo d'occhio. Una variabile denominata d potrebbe rappresentare data, durata, distanza o dati, richiedendo uno sforzo mentale per tracciarne lo scopo all'interno della funzione. Nomi descrittivi come userCreatedDate oppure requestDuration rendono l'intento immediatamente chiaro senza alcun carico cognitivo.

Perché è importante

Manutenibilità del codice: nomi di variabili poco chiari rallentano la comprensione. Gli sviluppatori perdono tempo a capire cosa rappresentano x, tmp o val invece di concentrarsi sulla logica effettiva. Una cattiva denominazione rende inoltre il codice più difficile da estendere, poiché non è chiaro dove debba trovare spazio la nuova logica o come i valori esistenti si relazionino tra loro. Oltre a ciò, nomi vaghi rendono la codebase impossibile da ricercare, dal momento che la ricerca di tmp o val non produce risultati significativi. Questo problema si amplifica quando si ritorna sul codice mesi dopo o quando si uniscono nuovi membri al team.

Introduzione di bug: Nomi ambigui aumentano la probabilità di utilizzare la variabile sbagliata. Quando più variabili hanno nomi criptici simili (d1, d2, d3), gli sviluppatori potrebbero usare quella errata, introducendo bug subdoli che superano la code review perché i nomi non forniscono indizi semantici.

Esempi di codice

❌ Non conforme:

function calcAmt(u, qty) {
    const p = u.prc;
    const d = u.disc || 0;
    const t = p * qty;
    const a = t - (t * d);
    const tx = a * 0.08;
    return a + tx;
}

Perché non è accurato: Nomi di variabili come u, p, d, t, e non rivelano nulla sul loro scopo. I lettori devono analizzare la logica di calcolo per capire che p è il prezzo, d è lo sconto, t è il subtotale e a è l'importo prima delle tasse.

✅ Conforme:

function calculateOrderAmount(product, quantity) {
    const price = product.price;
    const discount = product.discount || 0;
    const subtotal = price * quantity;
    const amountAfterDiscount = subtotal - (subtotal * discount);
    const tax = amountAfterDiscount * 0.08;
    return amountAfterDiscount + tax;
}

Perché questo è importante: Ogni nome di variabile descrive chiaramente il suo contenuto. amountAfterDiscount indica chiaramente lo stato del calcolo, tax è inequivocabile e product e quantity rivela gli input della funzione senza bisogno di leggerne il corpo.

Conclusione

Usa nomi che rivelano l'intento senza richiedere contesto. Prediligi la chiarezza alla brevità. I caratteri extra in totalPrice rispetto a tp non costano nulla in termini di esecuzione, ma fanno risparmiare molto tempo nella comprensione.