Migliorare nomi di funzioni, tipi e casi d’uso

Questa lezione appartiene al Modulo 22 — Refactoring avanzato e varianti.

Perché i nomi contano

Un nome è documentazione che non si aggiorna da sola. Un nome preciso dice cosa fa una funzione senza dover leggere il corpo. Un nome vago obbliga a leggere ogni riga per capire cosa succede.

Nel Registro del laboratorio, i nomi imprecisi si accumulano quando si scrive velocemente. Questa lezione insegna a riconoscerli e correggerli sistematicamente.

Tre categorie di nomi da migliorare

1. Funzioni del dominio

Le funzioni del dominio devono comunicare una regola del laboratorio o un’operazione sul modello.

// ❌ Nomi che non comunicano
function check(s) { return s.stato === "disponibile"; }
function update(s, stato) { return { ...s, stato }; }
function proc(id, lista) { return lista.find(x => x.id === id); }

// ✅ Nomi che comunicano la regola
function isDisponibile(strumento) { return strumento.stato === "disponibile"; }
function aggiornaStato(strumento, nuovoStato) { return { ...strumento, stato: nuovoStato }; }
function trovaPerId(id, lista) { return lista.find(s => s.id === id) ?? null; }

Regola: il nome deve contenere un verbo che descriva l’azione (trova, verifica, aggiorna, crea, apri, chiudi) e un sostantivo che descriva il soggetto (Strumento, Prestito, Stato).

2. Casi d’uso

I casi d’uso devono avere nomi che corrispondono alle azioni del laboratorio — le stesse parole usate dal personale scolastico.

// ❌ Nomi tecnici o generici
function handleForm() { ... }
function doSave(data) { ... }
function processRequest(req) { ... }

// ✅ Nomi del vocabolario del laboratorio
function registraStrumento(comando) { ... }
function registraPrestito(comando) { ... }
function chiudiPrestito(comando) { ... }
function apriSegnalazioneGuasto(comando) { ... }
function cercaStrumenti(filtri) { ... }

Il test: se un tecnico del laboratorio scolastico legge il nome della funzione, capisce cosa fa senza spiegazioni aggiuntive?

3. Variabili e parametri

// ❌ Nomi troppo corti o generici
function f(x, y) {
  const r = x.filter(i => i.s === y);
  return r;
}

// ✅ Nomi espliciti
function filtraPerStato(strumenti, stato) {
  const risultati = strumenti.filter(s => s.stato === stato);
  return risultati;
}

Eccezione accettata: variabili di ciclo brevi (i, j) in contesti ovvi come for (let i = 0; ...).

Pattern di rinomino nel Registro

Tabella di rinomino comune per il Registro del laboratorio:

Nome attuale	Problema	Nome migliore
data	generico	strumento, prestito, comando
item	generico	strumento o prestito
list / arr	generico	strumenti, prestiti
check	non dice cosa verifica	verificaDisponibilita, isGuasto
save	non dice cosa salva	salvaStrumento, salvaPrestito
get	non dice cosa prende	trovaPerId, leggiTutti
handleClick	troppo generico	gestisciSubmitPrestito, gestisciClickChiudi
update	non dice cosa aggiorna	aggiornaStatoStrumento
process	vago	registraPrestito, elaboraRichiesta

Come rinominare senza rompere nulla

Il rinomino è un refactoring — il comportamento non deve cambiare.

Procedura sicura:

1. Prima di rinominare, verifica che esista un test o uno scenario di verifica per la funzione.
2. Rinomina la funzione in tutti i punti in cui viene definita e chiamata.
3. Verifica che il progetto funzioni identicamente.
4. Aggiorna README, commenti e documentazione che citano il vecchio nome.

// Esempio: rinomino `check` → `puoEsserePrestato`

// Passo 1 — vecchio nome (prima)
function check(strumento) {
  return strumento.stato === "disponibile";
}
// Chiamato in: registraPrestito.js, ui.js

// Passo 2 — rinomina in tutti i punti
function puoEsserePrestato(strumento) {
  return strumento.stato === "disponibile";
}
// Aggiorna: registraPrestito.js → puoEsserePrestato(strumento)
//           ui.js → puoEsserePrestato(strumento)

// Passo 3 — verifica: il Registro funziona come prima

Esercizio — tre rinomini nel tuo progetto

1. Trova una funzione con nome vago nel dominio — rinominala.
2. Trova una variabile con nome generico (data, item, res) — rinominala.
3. Trova un caso d’uso con nome tecnico (handle, process, do) — rinominala con un verbo del laboratorio.

Per ogni rinomino: verifica che tutti i chiamanti siano aggiornati e che il comportamento sia identico.

Attività in classe

## Tre rinomini nel mio Registro

Rinomino 1 — funzione del dominio:
  - Nome attuale: 
  - Problema: 
  - Nome proposto: 
  - File dove appare (definizione + chiamanti): 
  - Verifica dopo il rinomino: 

Rinomino 2 — variabile o parametro:
  - Nome attuale: 
  - Problema: 
  - Nome proposto: 
  - File e riga: 

Rinomino 3 — caso d'uso:
  - Nome attuale: 
  - Problema: 
  - Nome proposto: 
  - Corrisponde al vocabolario del laboratorio (sì/no): 

Spiegazione guidata per studiare

I nomi sono la prima documentazione che un lettore incontra. Prima ancora di leggere il corpo di una funzione, il nome trasmette un’aspettativa. Se l’aspettativa è sbagliata, il lettore deve correggere la propria comprensione mentre legge — un costo cognitivo inutile.

Il punto centrale è: il nome deve corrispondere all’intenzione, non all’implementazione. aggiornaStato dice cosa fa la funzione. setField dice come lo fa internamente — e può diventare sbagliato se l’implementazione cambia.

Il rischio tipico è rinominare solo la definizione e dimenticare i chiamanti. Un editor moderno fa questo automaticamente con “rename symbol”. Se lo fai a mano, cerca tutte le occorrenze prima di modificare.

Passo per passo nel progetto

1. Apri domain/strumento.js. Ogni funzione ha un nome che comunica una regola del laboratorio?
2. Apri application/. Ogni caso d’uso ha un nome che un tecnico del laboratorio capirebbe?
3. Apri presentation/. Ogni handler ha un nome che dice quale azione dell’utente gestisce?
4. Per ogni nome da migliorare: elenca tutti i file dove appare prima di cambiarlo.
5. Rinomina uno alla volta — verifica dopo ogni rinomino.

Esempio da leggere lentamente

// Prima del rinomino — nomi che non comunicano
function proc(cmd, arch1, arch2) {
  const s = arch1.get(cmd.id);
  if (!s || s.s !== "ok") throw new Error("ERR");
  const p = make(s.id, cmd.chi);
  arch2.put(p);
  arch1.put({ ...s, s: "busy" });
  return p;
}

// Dopo il rinomino — stessa logica, nomi che comunicano
function registraPrestito(comando, archivioStrumenti, archivioPrestiti) {
  const strumento = archivioStrumenti.trovaPerId(comando.strumentoId);
  if (!strumento) throw new Error("STRUMENTO_NON_TROVATO");
  puoEsserePrestato(strumento); // lancia se non disponibile
  const prestito = apriPrestito(strumento.id, comando.assegnatario);
  archivioPrestiti.salva(prestito);
  archivioStrumenti.salva({ ...strumento, stato: "in_prestito" });
  return prestito;
}

Il comportamento è identico. La seconda versione si legge come una storia.

Prova di comprensione

• Trova nel tuo progetto tre funzioni con nome vago. Proponi un nome migliore per ognuna.
• Il nome gestisciSubmitPrestito è migliore di handleClick? Perché?
• Se rinomini check in puoEsserePrestato, quali file devi aggiornare nel tuo progetto?

Errori da evitare

• rinominare solo la definizione e dimenticare i chiamanti;
• scegliere nomi più lunghi senza essere più precisi (doProcessTheData non è migliore di process);
• usare nomi in inglese quando il dominio usa italiano — incoerenza che crea confusione;
• rinominare e cambiare la logica nello stesso commit — i refactoring di nome devono essere puri.

Prodotto da consegnare

Può essere:

• tre rinomini applicati nel codice con verifica che i chiamanti siano aggiornati;
• una tabella “nome attuale → nome proposto → motivazione” per cinque elementi del progetto;
• un commit che contiene solo rinomini (nessuna modifica logica).

Checklist di chiusura

• Ho trovato almeno tre nomi vaghi nel progetto
• Ho rinominato uno alla volta, verificando dopo ogni modifica
• Tutti i chiamanti di ogni funzione rinominata sono stati aggiornati
• Il comportamento del Registro è identico prima e dopo i rinomini
• I nuovi nomi usano il vocabolario del laboratorio (strumento, prestito, stato, archivio)

Domande per la revisione

• Dopo i rinomini, riesci a leggere il codice più velocemente?
• I nomi scelti sono comprensibili per un tecnico del laboratorio scolastico?
• Hai trovato nomi in inglese in un dominio che usa l’italiano? Come li hai gestiti?

Risultato atteso

Alla fine lo studente deve saper dire:

Ho rinominato queste funzioni/variabili nel Registro:
1. [nome vecchio] → [nome nuovo] in [file] — perché [motivazione]
2. [nome vecchio] → [nome nuovo] in [file] — perché [motivazione]
3. [nome vecchio] → [nome nuovo] in [file] — perché [motivazione]
Ho verificato che tutti i chiamanti sono aggiornati e il comportamento è identico.

Se questa spiegazione non è possibile, la lezione non è ancora davvero conclusa.