Preparare spiegazione delle scelte architetturali

Questa lezione appartiene al Modulo 16 — Progetto finale completo.

Cosa significa spiegare le scelte architetturali

Spiegare l’architettura non significa descrivere ogni file. Significa rispondere a tre domande:

1. Cosa hai deciso (struttura del progetto, separazione dei livelli, scelta dell’archivio)
2. Perché lo hai deciso (il problema che risolveva, l’alternativa scartata)
3. Quali conseguenze ha avuto (cosa è diventato più facile, cosa è rimasto difficile)

Una buona spiegazione architetturale è verificabile: chi la ascolta dovrebbe riuscire a trovare nel codice la prova di ciò che viene descritto.

Le tre scelte architetturali principali del Registro

Per la presentazione finale, prepara una spiegazione per ognuna di queste tre scelte:

Scelta 1: separazione dei quattro livelli

Cosa: il progetto è diviso in quattro cartelle — domain, application, infrastructure, presentation.

Perché: ogni livello ha una responsabilità diversa. Il dominio non sa dove
        vengono salvati i dati. I casi d'uso non sanno come viene mostrata la UI.
        Questa separazione permette di testare le regole senza browser e di
        cambiare l'archivio senza toccare le regole.

Conseguenze: aggiungere un nuovo stato a StatoStrumento richiede di toccare solo
             domain/strumento.js — non la UI, non l'archivio.
             Passare da localStorage a un'API richiede di scrivere un nuovo adapter
             in infrastructure/ — non modificare registraPrestito.

Scelta 2: archivio come dipendenza esplicita

Cosa: i casi d'uso ricevono l'archivio come parametro — non lo costruiscono internamente.

Perché: se il caso d'uso costruisse l'archivio internamente (new LocalStorageArchivio()),
        sarebbe impossibile testarlo senza localStorage. Passandolo come dipendenza,
        nei test si usa un archivio in memoria — veloce, senza side effect.

Conseguenze: creaRegistraPrestito({ archivioStrumenti, archivioPrestiti }) permette
             di sostituire entrambi gli archivi in un unico punto — main.js.

Scelta 3: errori come codici, messaggi nella Presentation

Cosa: il dominio e i casi d'uso lanciano errori con codici (STRUMENTO_NON_TROVATO).
      La Presentation traduce i codici in messaggi comprensibili per l'utente.

Perché: se il dominio lanciasse "Strumento non trovato.", non si potrebbe cambiare
        il testo senza toccare il dominio. Con i codici, il testo cambia solo
        nella Presentation — il dominio rimane stabile.

Conseguenze: aggiungere una lingua diversa (es. inglese) richiede di aggiornare
             solo il dizionario dei messaggi nella Presentation.

Come presentare una scelta architetturale oralmente

Struttura in tre frasi:

"Abbiamo deciso di [cosa].
 Lo abbiamo fatto perché [problema che risolveva / alternativa scartata].
 La conseguenza pratica è che [cosa è diventato più facile]."

Esempio:

"Abbiamo deciso di tenere il dominio separato da localStorage.
 Lo abbiamo fatto perché se il dominio chiamasse localStorage direttamente,
 non potremmo testarlo senza un browser e non potremmo cambiare archivio senza
 riscrivere le regole.
 La conseguenza pratica è che i test del dominio funzionano con oggetti in memoria
 — non serve avviare il browser per verificare che uno strumento guasto non possa
 essere prestato."

Come dimostrare la scelta nel codice

Ogni scelta deve avere una prova nel codice. Prepara per la presentazione:

Scelta	Dove si vede nel codice
Dominio separato da localStorage	domain/strumento.js non importa nulla — nessun import esterno
Archivio come dipendenza	creaRegistraPrestito({ archivioStrumenti, archivioPrestiti }) in application/
Errori come codici	throw new Error("STRUMENTO_NON_TROVATO") nel caso d’uso, dizionario in presentation/
Test senza browser	file di test che usa creaArchivioStrumentiInMemoria()

Durante la presentazione: apri il file, indica la riga, spiega cosa dimostra.

Prepara la spiegazione per ogni scelta

Usa questo schema per ognuna delle tre scelte:

SCELTA: [nome breve]
DOVE SI VEDE: [file:riga o nome della funzione]
COSA: [una frase]
PERCHÉ: [una frase — il problema risolto]
CONSEGUENZA: [una frase — cosa è diventato più facile]
LIMITE: [una frase — cosa è rimasto difficile o non risolto]

Procedura guidata

1. Leggi le tre scelte architetturali principali sopra.
2. Per ognuna: trova nel tuo codice il punto che la dimostra (file e riga).
3. Scrivi la spiegazione in tre frasi (cosa, perché, conseguenza).
4. Prova a spiegarla a un compagno in 60 secondi — senza leggere le note.
5. Se il compagno non capisce la conseguenza, la spiegazione è troppo astratta.

Attività in classe

## Spiegazione delle scelte architetturali

Scelta 1 — Separazione dei quattro livelli:
  - Dove si vede nel codice: 
  - Cosa: 
  - Perché: 
  - Conseguenza: 
  - Limite: 

Scelta 2 — Archivio come dipendenza esplicita:
  - Dove si vede nel codice: 
  - Cosa: 
  - Perché: 
  - Conseguenza: 
  - Limite: 

Scelta 3 — Errori come codici:
  - Dove si vede nel codice: 
  - Cosa: 
  - Perché: 
  - Conseguenza: 
  - Limite: 

Prova orale (60 secondi per scelta): eseguita con [nome compagno]
Feedback ricevuto: 

Spiegazione guidata per studiare

Una spiegazione architetturale è convincente quando è verificabile. Non basta dire “il dominio è separato dall’infrastruttura” — bisogna poter aprire un file e mostrarlo.

Il punto centrale è: ogni scelta ha una prova nel codice. Se non riesci a trovare la prova, o la scelta non è stata implementata davvero, o la spiegazione è troppo astratta.

Il rischio tipico è descrivere l’architettura come si vorrebbe che fosse, non come è effettivamente. Prima della presentazione, verifica che ogni scelta descritta abbia un corrispondente nel codice. Se non ce l’ha, o la descrizione è sbagliata o il codice è incompleto.

Passo per passo nel progetto

1. Apri domain/strumento.js — importa qualcosa da infrastructure/ o da localStorage? Se sì, c’è un problema da correggere prima della presentazione.
2. Apri un caso d’uso — riceve l’archivio come parametro o lo costruisce internamente? Se lo costruisce internamente, c’è una dipendenza nascosta.
3. Cerca throw new Error( nei casi d’uso — i messaggi sono codici (STRUMENTO_NON_TROVATO) o frasi in italiano ("Strumento non trovato")?
4. Per ogni problema trovato: correggilo prima della presentazione.

Esempio da leggere lentamente

Spiegazione della scelta "dominio separato da localStorage" — versione corretta:

"Nel nostro Registro, le funzioni in domain/strumento.js non chiamano mai localStorage.
Questo significa che possiamo testare tutte le regole di prestabilità — strumento guasto,
strumento già in prestito — usando solo oggetti JavaScript in memoria, senza avviare
il browser. La separazione è visibile in domain/strumento.js: il file non ha nessun
import esterno. L'unico limite è che la coerenza tra lo stato dello strumento e i
prestiti aperti non è garantita atomicamente — se il salvataggio del prestito riesce
ma quello dello strumento fallisce, i dati diventano incoerenti."

Questa spiegazione ha: cosa (nessuna chiamata a localStorage), perché (testabilità), prova (nessun import), limite (coerenza non atomica). È completa.

Prova di comprensione

• Riesci a spiegare la scelta “archivio come dipendenza” in 60 secondi?
• Dove nel tuo codice si vede che il dominio non usa localStorage?
• Qual è il limite principale della tua implementazione attuale?

Errori da evitare

• descrivere scelte architetturali che non sono state implementate (es. “il dominio è puro” quando in realtà ha una chiamata a localStorage);
• spiegare l’architettura senza mostrare il codice — è solo teoria;
• non menzionare i limiti — ogni scelta ha un trade-off, nominarli è un punto di forza, non di debolezza;
• usare termini tecnici senza definirli per l’audience (es. “dependency injection” senza spiegare cosa significa).

Prodotto da consegnare

Può essere:

• la scheda compilata con le tre spiegazioni (cosa, perché, conseguenza, limite, prova nel codice);
• una prova orale di 3 minuti registrata o eseguita davanti al docente;
• una sezione “Scelte architetturali” nel README con le tre spiegazioni.

Checklist di chiusura

• Ho trovato nel codice la prova di ognuna delle tre scelte architetturali
• So spiegare ogni scelta in 60 secondi con: cosa, perché, conseguenza
• Ho nominato almeno un limite per ogni scelta
• Ho provato la spiegazione oralmente con un compagno
• Il README ha una sezione sulle scelte architetturali

Domande per la revisione

• Il compagno ha capito le conseguenze pratiche delle scelte? Se no, cosa andava chiarito?
• Hai trovato una scelta descritta ma non implementata nel codice?
• Quale dei tre limiti nominati è il più importante da risolvere in una versione futura?

Risultato atteso

Alla fine lo studente deve saper dire:

La scelta architetturale principale del mio Registro è [X].
Si vede in [file:funzione].
L'ho fatta perché [problema risolto].
La conseguenza è che [cosa è diventato più facile].
Il limite principale è [cosa è rimasto difficile].

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