Il codice viene letto molte più volte di quante venga scritto. Lo legge chi lo revisiona, chi lo corregge, chi aggiunge una funzione mesi dopo, spesso lo stesso autore che nel frattempo ha dimenticato tutto. In questa lettura continua, i nomi sono la forma di documentazione più immediata: un buon nome fa capire in un istante cosa contiene una variabile o cosa fa una funzione; un cattivo nome costringe a leggere il codice riga per riga per ricostruirlo.
Il nome deve rivelare l'intenzione
Confronta queste due versioni della stessa riga:
d = 86400
SECONDI_IN_UN_GIORNO = 86400
La seconda non richiede commenti. Un buon nome risponde a tre domande: che cosa rappresenta questo valore, perché esiste, come va usato. Se per spiegare un nome serve un commento, di solito il nome va cambiato.
Un altro esempio, una funzione:
def elabora(lista):
return [x for x in lista if x.stato == "A" and x.saldo > 0]
def clienti_attivi_con_credito(clienti):
return [c for c in clienti if c.e_attivo() and c.saldo > 0]
La logica è identica, ma la seconda versione si capisce senza conoscere il significato del codice di stato "A".
Regole pratiche
Includi le unità di misura
Una variabile chiamata timeout può essere in secondi o in millisecondi, e la differenza può causare bug difficili da trovare. timeout_secondi o durata_ms eliminano l'ambiguità. Lo stesso vale per valute, distanze, dimensioni in byte o in kilobyte.
Booleani che si leggono come domande
I valori vero/falso dovrebbero avere nomi che suonano come una domanda con risposta sì o no: e_valido, ha_permessi, puo_modificare, is_active. Evita le negazioni: non_disabilitato costringe a una doppia negazione mentale ogni volta che lo si legge, soprattutto in espressioni come if not non_disabilitato.
Funzioni con un verbo
Le funzioni compiono azioni, quindi il nome inizia di solito con un verbo: calcola_totale, invia_notifica, carica_configurazione. Le funzioni che restituiscono un booleano seguono la regola delle domande: e_scaduto(abbonamento).
Lunghezza proporzionata alla portata
Un indice in un ciclo di tre righe può chiamarsi i senza problemi: il contesto è tutto lì, visibile. Una variabile usata in tutto un modulo, invece, merita un nome completo e descrittivo. La regola: più ampia è la portata, più il nome deve essere esplicito.
Coerenza nel vocabolario
Se in una parte del codice si usa recupera_utente, in un'altra ottieni_cliente e altrove carica_account per operazioni equivalenti, chi legge si chiederà se ci sono differenze. Scegli un termine per ogni concetto e usalo ovunque. Vale anche per i concetti del dominio: se l'azienda parla di «pratiche», il codice non dovrebbe parlare di «ticket».
Errori frequenti
| Nome debole | Problema | Alternativa |
|---|---|---|
data |
Troppo generico, non dice cosa contiene | ordini_del_mese |
temp, tmp |
Non spiega il ruolo del valore | prezzo_senza_iva |
lista_utenti (che è un insieme) |
Il nome mente sul tipo | utenti |
gestore, manager |
Dice poco sulla responsabilità | pianificatore_spedizioni |
x1, x2 |
Nessun significato | prezzo_iniziale, prezzo_finale |
flag |
Non dice cosa indica | richiede_approvazione |
Il caso del nome che "mente" è il più insidioso: una variabile chiamata utenti_attivi che in realtà contiene anche utenti sospesi porta a decisioni sbagliate da parte di chi si fida del nome. Quando il significato di un valore cambia, il nome va aggiornato.
Convenzioni del linguaggio
Ogni linguaggio ha convenzioni di scrittura che vale la pena rispettare, perché rendono il codice familiare a chiunque lo conosca:
- in Python,
snake_caseper variabili e funzioni,PascalCaseper le classi,MAIUSCOLO_CON_UNDERSCOREper le costanti; - in JavaScript e Java,
camelCaseper variabili e funzioni,PascalCaseper le classi.
Un'altra decisione da prendere a livello di team è la lingua dei nomi. Molti progetti scelgono l'inglese, che si sposa con le parole chiave del linguaggio e con le librerie; altri usano l'italiano per i concetti di dominio, perché aderiscono meglio al linguaggio dei clienti. Entrambe le scelte sono legittime; il mescolamento casuale, come getCliente accanto a fetch_customer, non lo è.
Rinominare senza paura
Un nome sbagliato non è una condanna. Gli editor moderni offrono funzioni di rinomina automatica che aggiornano tutte le occorrenze in modo sicuro, e una buona suite di test conferma che nulla si è rotto. Nel mio lavoro, quando torno su un codice e impiego più di qualche secondo a capire cosa rappresenta una variabile, la rinomino subito: è uno dei refactoring più economici e con il ritorno più alto.
In sintesi
- I nomi sono la documentazione più letta: devono rivelare cosa rappresenta un valore e perché esiste.
- Includi le unità di misura e dai ai booleani la forma di una domanda.
- Usa verbi per le funzioni e nomi tanto più espliciti quanto più ampia è la loro portata.
- Mantieni un vocabolario coerente e rispetta le convenzioni del linguaggio.
- Rinomina appena un nome non è più chiaro o non corrisponde più al contenuto.
