Micro-sfida: documenta perché il dominio non usa localStorage

Questa lezione appartiene al Modulo 15 — Struttura del progetto, documentazione e diagrammi.

La sfida

Scrivi una decisione tecnica breve — una nota di 5-10 righe — che risponde a questa domanda:

Perché le funzioni in domain/ non chiamano mai localStorage direttamente?

La nota deve essere comprensibile a qualcuno che arriva sul progetto per la prima volta, senza dover leggere tutto il codice.

Perché documentare questa scelta

Questa è una delle decisioni architetturali più importanti del progetto. Senza una spiegazione, chi arriva dopo (o tu stesso tra tre mesi) potrebbe pensare che sia una dimenticanza e aggiungere localStorage.setItem(...) direttamente in una funzione del dominio.

Una nota scritta rende la scelta esplicita e difende il confine.

Struttura di una buona decisione tecnica

Una decisione tecnica breve ha questa forma:

## Decisione: [cosa è stato deciso]

**Contesto:** [perché si è posta la questione]

**Scelta:** [cosa abbiamo deciso di fare]

**Motivazione:** [perché — il ragionamento]

**Conseguenze:** [cosa cambia, cosa non cambia, cosa diventa più facile/difficile]

Non serve essere esaurienti. Serve essere chiari sul “perché”.

Esempio da completare

Leggi questa bozza incompleta e completala con parole tue:

## Decisione: il dominio non usa localStorage

**Contesto:** il Registro del laboratorio salva strumenti e prestiti in localStorage.
Potremmo chiamare localStorage direttamente dalle funzioni del dominio per semplicità.

**Scelta:** le funzioni in `domain/` non chiamano mai localStorage, fetch o qualsiasi
altro sistema di salvataggio. Questa responsabilità appartiene a `infrastructure/`.

**Motivazione:** [completa con 2-3 frasi — perché questa scelta è importante?]

**Conseguenze:**
- I test del dominio non hanno bisogno di localStorage — funzionano con oggetti in memoria.
- [aggiungi un'altra conseguenza positiva]
- Se domani cambiamo da localStorage a un database, [cosa non cambia?]

Risposta di riferimento

Dopo aver scritto la tua versione, confronta con questa:

## Decisione: il dominio non usa localStorage

**Contesto:** il Registro del laboratorio salva strumenti e prestiti in localStorage.
Potremmo chiamare localStorage direttamente dalle funzioni del dominio per semplicità.

**Scelta:** le funzioni in `domain/` non chiamano mai localStorage, fetch o qualsiasi
altro sistema di salvataggio. Questa responsabilità appartiene a `infrastructure/`.

**Motivazione:** il dominio contiene le regole del laboratorio — regole che devono
valere indipendentemente da dove i dati vengono salvati. Se il dominio conosce
localStorage, non può essere usato con un database o un'API senza riscrivere le
regole. Separando le responsabilità, le regole restano stabili mentre l'infrastruttura
può cambiare.

**Conseguenze:**
- I test del dominio non hanno bisogno di localStorage — funzionano con oggetti in memoria.
- Se domani cambiamo da localStorage a un'API, le regole del dominio non cambiano.
- Aggiungere un nuovo tipo di archivio richiede solo un nuovo adapter in `infrastructure/`,
  non modifiche al dominio.

Dove mettere la nota

Tre opzioni valide — scegline una:

1. Nel README, in una sezione “Decisioni tecniche” o “Architettura”
2. In un file docs/decisioni.md dedicato alle scelte architetturali
3. Come commento in domain/strumento.js, vicino all’inizio del file

// domain/strumento.js
//
// NOTA ARCHITETTURALE: questo modulo non usa localStorage, fetch o altri
// sistemi di I/O. Il salvataggio è responsabilità di infrastructure/.
// Questa separazione permette di testare le regole senza browser e di
// cambiare archivio senza toccare il dominio.

La sfida completa

1. Scrivi la decisione tecnica con parole tue (non copiare la risposta di riferimento).
2. Posizionala in un posto visibile del progetto (README, docs/, o commento).
3. Verifica che risponda a: cosa, perché, conseguenze.
4. Chiedi a un compagno di leggerla: capisce la scelta senza spiegazioni aggiuntive?

Attività in classe

## Documentazione della scelta architetturale

Formato scelto (README / docs/decisioni.md / commento nel codice):

Bozza della decisione tecnica:

Feedback ricevuto da un compagno:

Versione finale posizionata nel progetto:

Spiegazione guidata per studiare

Documentare una decisione architetturale non significa spiegare come funziona il codice — il codice già lo fa. Significa spiegare perché il codice è strutturato in quel modo, così che chi viene dopo non cambi la struttura per sbaglio.

Il punto centrale è: una scelta non documentata sembra una dimenticanza. Se il dominio non usa localStorage e non c’è nessuna nota, qualcuno aggiungerà localStorage.setItem in una funzione del dominio convinto di migliorare il codice. Con una nota, la scelta è difesa.

Il rischio tipico è scrivere note troppo lunghe o troppo tecniche. Una decisione tecnica efficace ha tre parti: cosa, perché, conseguenze. Non serve altro.

Passo per passo nel progetto

1. Cerca nel tuo progetto: esiste già una nota che spiega perché il dominio è separato dall’infrastruttura?
2. Se no, apri il README o crea docs/decisioni.md.
3. Scrivi la decisione tecnica in 5-10 righe usando la struttura: contesto, scelta, motivazione, conseguenze.
4. Verifica che un compagno la capisca senza aiuto.
5. Se la decisione è nel README, verifica che sia in una sezione chiaramente identificata.

Esempio da leggere lentamente

## Perché il dominio non conosce localStorage

Il dominio del Registro contiene le regole del laboratorio: quali strumenti possono
essere prestati, quando un prestito è valido, quali stati sono ammessi.

Queste regole devono valere sempre — indipendentemente da dove i dati vengono salvati.
Se il dominio chiamasse localStorage, non potremmo testarlo senza un browser, e non
potremmo passare a un database senza riscrivere le regole.

Per questo, il dominio riceve i dati come parametri e restituisce risultati.
Il salvataggio è compito dell'infrastruttura.

Questa nota ha 60 parole. È sufficiente.

Prova di comprensione

• Riesci a spiegare la scelta in meno di tre frasi?
• La tua nota risponde a “cosa è stato deciso” E a “perché”?
• Un compagno che non conosce il progetto capisce la nota?

Errori da evitare

• scrivere una nota che spiega come funziona il codice invece del perché;
• essere troppo tecnici (stack trace, nomi di funzioni specifiche) — la nota deve reggere nel tempo;
• non indicare le conseguenze — “cosa cambia” è la parte più utile per chi deve modificare il codice;
• nascondere la nota in un posto difficile da trovare.

Prodotto da consegnare

Può essere:

• una sezione “Decisioni tecniche” nel README con almeno questa decisione documentata;
• un file docs/decisioni.md con la nota;
• un commento all’inizio di domain/strumento.js che spiega la scelta.

In tutti i casi: la nota deve essere visibile, breve e rispondere a contesto, scelta, motivazione, conseguenze.

Checklist di chiusura

• La decisione tecnica è scritta con parole mie (non copiata)
• Risponde a: cosa è stato deciso, perché, conseguenze
• È posizionata in un posto visibile del progetto
• Un compagno ha letto la nota e l’ha capita senza spiegazioni aggiuntive
• La nota non spiega come funziona il codice — spiega perché è strutturato così

Domande per la revisione

• Quanto tempo ci ha messo il tuo compagno a capire la nota?
• Hai dovuto aggiungere spiegazioni verbali? Se sì, cosa mancava nella nota?
• Quali altre decisioni architetturali del Registro meriterebbero una nota simile?

Risultato atteso

Alla fine lo studente deve poter mostrare:

Ho scritto questa decisione tecnica: [testo della nota]
È posizionata in: [README / docs/decisioni.md / commento in domain/]
Un compagno l'ha letta e ha capito: [cosa ha capito, eventuali dubbi]

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