JavaScript: scrivere codice pulito con naming chiaro, costante e intenzionale

by Anastasia P.
Add as preferred source on Google
SHARE
JavaScript: scrivere codice pulito con naming chiaro, costante e intenzionale
© Guida-HTML5.it

Introduzione

Quando si parla di best practices e di codice pulito in JavaScript, spesso si pensa subito a funzioni pure, modularizzazione o gestione degli errori. Un aspetto altrettanto importante, però, è la qualità dei nomi che diamo a variabili, funzioni, parametri e costanti.

Un nome ben scelto riduce la necessità di commenti, rende il codice più leggibile e aiuta chi lavora sul progetto a capire subito cosa fa una parte di codice e perché esiste. Al contrario, nomi generici come data, temp, result o value diventano rapidamente un problema quando il codice cresce.

In questo tutorial vediamo un sotto-argomento molto pratico: come scrivere naming chiaro e intenzionale in JavaScript. È un tema semplice solo in apparenza, ma ha un impatto enorme sulla manutenzione, sul debugging e sulla collaborazione in team.

Codice completo

// Esempio: gestione di un carrello e calcolo del totale
// Obiettivo: usare nomi chiari, coerenti e facilmente comprensibili

const TAX_RATE = 0.22;
const FREE_SHIPPING_THRESHOLD = 50;

const cartItems = [
  { name: "T-shirt", price: 19.9, quantity: 2 },
  { name: "Book", price: 14.5, quantity: 1 },
  { name: "Cap", price: 12, quantity: 1 }
];

function calculateItemSubtotal(item) {
  return item.price * item.quantity;
}

function calculateCartSubtotal(items) {
  return items.reduce((total, item) => {
    return total + calculateItemSubtotal(item);
  }, 0);
}

function calculateTaxAmount(subtotal, taxRate) {
  return subtotal * taxRate;
}

function calculateShippingCost(subtotal) {
  return subtotal >= FREE_SHIPPING_THRESHOLD ? 0 : 4.99;
}

function calculateOrderTotal(items) {
  const subtotal = calculateCartSubtotal(items);
  const taxAmount = calculateTaxAmount(subtotal, TAX_RATE);
  const shippingCost = calculateShippingCost(subtotal);

  return subtotal + taxAmount + shippingCost;
}

function formatCurrency(amount) {
  return new Intl.NumberFormat("it-IT", {
    style: "currency",
    currency: "EUR"
  }).format(amount);
}

const subtotal = calculateCartSubtotal(cartItems);
const taxAmount = calculateTaxAmount(subtotal, TAX_RATE);
const shippingCost = calculateShippingCost(subtotal);
const orderTotal = calculateOrderTotal(cartItems);

console.log("Riepilogo ordine");
console.log("Subtotale:", formatCurrency(subtotal));
console.log("IVA:", formatCurrency(taxAmount));
console.log("Spedizione:", formatCurrency(shippingCost));
console.log("Totale:", formatCurrency(orderTotal));

Spiegazione

Questo esempio mostra un principio fondamentale: il nome giusto racconta il ruolo del dato. Non abbiamo usato variabili come x, tmp o res, perché avrebbero reso il codice più difficile da leggere.

1. Costanti con significato preciso

Le costanti TAX_RATE e FREE_SHIPPING_THRESHOLD descrivono chiaramente il loro scopo. Non sono numeri “magici” sparsi nel codice, ma valori intenzionali con un significato di business.

Per esempio, invece di scrivere:

if (subtotal >= 50) { ... }

è molto meglio usare:

if (subtotal >= FREE_SHIPPING_THRESHOLD) { ... }

In questo modo, chi legge capisce subito che quel numero non è casuale.

2. Nomi di funzioni che descrivono l’azione

Le funzioni calculateItemSubtotal, calculateCartSubtotal, calculateTaxAmount e calculateShippingCost spiegano esattamente cosa fanno. Questo è un vantaggio enorme perché il codice diventa quasi auto-documentante.

Confronta questi due stili:

// Poco chiaro
function calc(a, b) {
  return a * b;
}

// Chiaro
function calculateTaxAmount(subtotal, taxRate) {
  return subtotal * taxRate;
}

Nel secondo caso non devi aprire subito la funzione per capire il comportamento.

3. Parametri coerenti con il dominio

Usare nomi come items, subtotal, taxRate e shippingCost aiuta a mantenere il codice vicino al linguaggio del dominio applicativo. Se stai lavorando su un e-commerce, il lessico del carrello, del totale e della spedizione è naturale e utile.

Questo approccio riduce anche gli errori: un parametro chiamato data può contenere qualsiasi cosa, mentre cartItems lascia pochissimi dubbi.

4. Evitare abbreviazioni ambigue

Le abbreviazioni sono accettabili solo se davvero standard nel team o nel settore. Per esempio, qty può essere comprensibile in contesti e-commerce, ma in molti casi quantity è più leggibile e non costa nulla in termini di chiarezza.

Meglio scrivere un po’ di più e far capire il codice al primo colpo, invece di risparmiare tre lettere e perdere minuti ogni volta che si legge il file.

5. Il ruolo delle variabili temporanee

Nel codice pulito, anche le variabili temporanee devono avere un ruolo chiaro. Nel nostro esempio:

  • subtotal rappresenta il totale prima di tasse e spedizione
  • taxAmount rappresenta l’importo dell’IVA
  • shippingCost rappresenta il costo della spedizione
  • orderTotal rappresenta il totale finale

Questi nomi aiutano a seguire il flusso dei calcoli senza dover ricostruire mentalmente ogni passaggio.

Best practice

  • Usa nomi che descrivano l’intento: una variabile deve dire cosa rappresenta, non solo che tipo di dato contiene.
  • Preferisci nomi completi e leggibili: calculateShippingCost è meglio di calcShip.
  • Evita numeri magici: sostituiscili con costanti ben nominate.
  • Usa il linguaggio del dominio: se lavori su pagamenti, ordini o utenti, adotta termini coerenti con quel contesto.
  • Non riutilizzare nomi per scopi diversi: una variabile chiamata data non dovrebbe cambiare significato nel tempo.
  • Sii coerente nello stile: se usi il camelCase per le funzioni, mantienilo in tutto il progetto.
  • Rinomina quando il significato evolve: se una funzione cresce e fa più cose, il nome deve rifletterlo con precisione.
  • Evita nomi troppo generici: result, temp, item vanno bene solo se il contesto è davvero ovvio.

Una buona domanda da farsi durante la scrittura è: “Se un collega legge questo nome fuori contesto, capisce cosa significa?” Se la risposta è no, il nome probabilmente va migliorato.

Riepilogo

Scrivere codice pulito in JavaScript non significa solo usare funzioni brevi o evitare duplicazioni. Significa anche dare ai nomi un ruolo centrale nella leggibilità del progetto. Un naming chiaro:

  • riduce il carico mentale durante la lettura;
  • rende il codice più facile da testare e modificare;
  • aiuta il team a comunicare meglio;
  • previene ambiguità e bug legati a interpretazioni errate.

Se vuoi migliorare davvero la qualità del tuo JavaScript, inizia dai nomi. Spesso è il refactoring più semplice e più efficace che puoi fare.

Approfondisci con risorse ufficiali

Add as preferred source on Google
SHARE