README: come far capire il progetto a chi arriva dopo

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

Il test del README

Un buon README supera questo test: dai il progetto a un compagno che non ha lavorato con te. Senza spiegazioni verbali, riesce ad avviarlo e capire cosa fa?

Se ci riesce, il README è sufficiente. Se deve fare domande, manca qualcosa.

La differenza tra README iniziale e README per chi arriva dopo

Il README iniziale (lezione 129) spiega come avviare. Il README per chi arriva dopo spiega anche perché il progetto è organizzato così — le scelte, i confini, i limiti. È la versione che un collaboratore futuro (o il docente) legge per capire il lavoro svolto.

Struttura del README completo

# Registro del laboratorio scolastico

Breve descrizione (2 righe):
Sistema per tracciare strumenti, prestiti e guasti nel laboratorio scolastico.
Gira nel browser, salva i dati in localStorage, non richiede server.

## Come avviare

```sh
# Opzione 1: server locale (consigliata — i moduli JS funzionano)
python3 -m http.server 8000
# poi apri http://localhost:8000

# Opzione 2: aprire index.html direttamente
# Funziona solo se il browser non blocca i moduli ES (Firefox lo permette)

Struttura del progetto

src/
  domain/         → regole del laboratorio (strumento, prestito, stati)
  application/    → casi d'uso (registraStrumento, registraPrestito, ...)
  infrastructure/ → salvataggio (localStorage, archivio in memoria per test)
  presentation/   → UI, form, gestione eventi
main.js           → punto di avvio — qui si compone tutto

Il dominio non conosce localStorage. I casi d’uso ricevono l’archivio come dipendenza. Questo permette di testare le regole senza browser.

Funzioni principali

• Registrare uno strumento con nome, categoria e stato iniziale
• Aprire un prestito (assegna uno strumento a uno studente)
• Chiudere un prestito (restituisce lo strumento)
• Segnalare un guasto (blocca il prestito dello strumento)
• Cercare strumenti per nome, categoria o stato

Scelte architetturali

Dominio separato da localStorage: le regole del laboratorio non dipendono da come vengono salvati i dati. Questo permette di testare le regole con oggetti in memoria.

Archivio come dipendenza: i casi d’uso ricevono l’archivio come parametro. Per cambiare da localStorage a un’API, si modifica solo main.js.

Errori come codici: il dominio usa codici (STRUMENTO_NON_TROVATO). La UI traduce i codici in messaggi comprensibili. Testo e logica sono separati.

Limiti noti

• localStorage: i dati si perdono se si cancella la cache del browser
• Nessuna autenticazione: chiunque con accesso al browser può modificare i dati
• Coerenza non garantita: se il browser si chiude durante un’operazione, i dati potrebbero diventare incoerenti (prestito salvato, stato strumento non aggiornato)

Come eseguire i test

# Con Node.js
node --test src/test/

# Con Vitest (se configurato)
npx vitest run

Miglioramenti futuri

• Aggiungere autenticazione per distinguere docente, tecnico e studente
• Sostituire localStorage con un database per garantire coerenza atomica
• Aggiungere esportazione del registro in CSV o PDF

## Come scrivere la sezione "Struttura del progetto"

La sezione struttura non è un elenco di file — è una spiegazione di responsabilità:

```txt
❌ Troppo tecnico e inutile:
src/
  strumento.js
  prestito.js
  archivio.js
  ui.js

✅ Con responsabilità:
src/
  domain/         → contiene StatoStrumento, creaStrumento, puoEsserePrestato
                    Non importa localStorage né la UI.
  application/    → contiene registraStrumento, registraPrestito, chiudiPrestito
                    Coordina le operazioni, non decide le regole.
  infrastructure/ → contiene creaArchivioStrumentiLocalStorage
                    Salva e legge dati. Sostituibile senza toccare il dominio.
  presentation/   → contiene avviaUI, renderListaStrumenti
                    Legge input, chiama casi d'uso, mostra risultati.

Come scrivere la sezione “Limiti noti”

I limiti sono un punto di forza, non di debolezza. Chi li dichiara dimostra di capire il progetto.

❌ Nessun limite dichiarato → chi arriva dopo non sa cosa aspettarsi

✅ Limiti concreti e motivati:
- "I dati non sono transazionali: se si aggiorna il prestito ma il processo si
   interrompe prima di aggiornare lo strumento, i due dati diventano incoerenti.
   Questo non è un bug del codice — è un limite di localStorage."

- "Non c'è autenticazione. Chiunque abbia accesso al browser può modificare
   qualsiasi dato. Accettabile per un progetto scolastico, non per produzione."

Il test del README in classe

Procedura:

1. Stampa o condividi il tuo README con un compagno che non conosce il tuo progetto.
2. Il compagno ha 5 minuti per leggere il README e avviare il progetto.
3. Senza aiuto verbale da parte tua.
4. Dopo 5 minuti: il compagno risponde a queste domande senza guardare il codice:
   • Cosa fa il Registro?
   • Come si avvia?
   • Perché il dominio è separato dall’infrastruttura?
   • Qual è il limite principale?

Se risponde correttamente a tutte e quattro, il README è sufficiente.

Procedura guidata

1. Apri il tuo README — esiste? Ha le sezioni fondamentali?
2. Completa la sezione “Come avviare” con i comandi esatti.
3. Scrivi la sezione “Struttura del progetto” con le responsabilità, non solo i nomi dei file.
4. Aggiungi almeno una scelta architetturale con motivazione.
5. Aggiungi almeno un limite noto con spiegazione.
6. Fai leggere il README a un compagno — raccogli feedback.

Attività in classe

## README — verifica di comprensione

Compagno che ha letto il README:

Domande poste dopo 5 minuti (senza guardare il codice):

1. Cosa fa il Registro?
   Risposta del compagno:        Corretta (sì/no)

2. Come si avvia?
   Risposta del compagno:        Corretta (sì/no)

3. Perché il dominio è separato da localStorage?
   Risposta del compagno:        Corretta (sì/no)

4. Qual è il limite principale?
   Risposta del compagno:        Corretta (sì/no)

Sezioni da migliorare in base al feedback:

Spiegazione guidata per studiare

Un README per chi arriva dopo deve rispondere a tre domande nell’ordine giusto: cosa fa questo progetto, come lo avvio, perché è costruito così. La terza domanda è quella più spesso omessa — e quella più utile per chi deve fare una modifica.

Il punto centrale è: il README è il biglietto da visita del progetto. Un valutatore che non conosce il tuo progetto forma la prima impressione leggendo il README prima ancora di aprire il codice. Se il README è incompleto o confuso, il codice deve fare un lavoro doppio per recuperare.

Il rischio tipico è scrivere il README per sé stessi — “lo so già, quindi non ho bisogno di spiegare”. Il README va scritto per chi non sa nulla del progetto.

Passo per passo nel progetto

1. Apri il README attuale. Quante sezioni ha? Quali mancano?
2. Scrivi la sezione “Come avviare” con i comandi copiabili e incollabili.
3. Scrivi la sezione “Struttura” con le responsabilità di ogni cartella.
4. Aggiungi le scelte architetturali (minimo una con motivazione).
5. Aggiungi i limiti noti (minimo uno con spiegazione).
6. Fai il test: dai il README a un compagno senza spiegazioni aggiuntive.

Esempio da leggere lentamente

Sezione "Struttura del progetto" — versione efficace:

## Struttura del progetto

src/domain/         → Regole del laboratorio.
                      Non conosce localStorage, fetch o la UI.
                      Può essere testato con oggetti in memoria.

src/application/    → Casi d'uso: cosa il sistema sa fare.
                      Riceve l'archivio come dipendenza — non lo costruisce internamente.

src/infrastructure/ → Salvataggio dei dati.
                      Oggi usa localStorage. Sostituibile con un'API senza toccare il dominio.

src/presentation/   → Interfaccia utente.
                      Legge input, chiama i casi d'uso, mostra risultati.
                      Non contiene regole del laboratorio.

main.js             → Punto di avvio.
                      Costruisce archivi, crea casi d'uso, avvia la UI.
                      È l'unico file che sa quale archivio si usa.

Prova di comprensione

• Il tuo README ha la sezione “Come avviare” con comandi che funzionano?
• La sezione “Struttura” spiega le responsabilità o solo i nomi dei file?
• Hai dichiarato almeno un limite noto? È spiegato con le conseguenze concrete?

Errori da evitare

• scrivere “vedi il codice per i dettagli” — il README deve essere autonomo;
• non aggiornare il README dopo le ultime modifiche al codice;
• scrivere solo la parte tecnica e omettere le scelte (il “perché”);
• non menzionare i limiti — chi arriva dopo li scoprirà in modo peggiore.

Prodotto da consegnare

Può essere:

• il README aggiornato con le sezioni: avvio, struttura, scelte, limiti;
• il test di comprensione compilato con le risposte del compagno;
• il feedback ricevuto e le sezioni riviste in base al feedback.

Checklist di chiusura

• Il README ha una sezione “Come avviare” con comandi esatti
• La sezione “Struttura” descrive le responsabilità, non solo i nomi
• Almeno una scelta architetturale è documentata con motivazione
• Almeno un limite noto è dichiarato con spiegazione delle conseguenze
• Il README è stato letto da un compagno senza spiegazioni verbali
• Il compagno ha risposto correttamente alle quattro domande di verifica

Domande per la revisione

• Il compagno ha capito cosa fa il Registro in 5 minuti? Se no, cosa mancava?
• La sezione “Struttura” ha aiutato a orientarsi nel codice?
• I limiti dichiarati sono stati chiari o hanno creato confusione?

Risultato atteso

Alla fine lo studente deve saper dire:

Il mio README ha queste sezioni: [lista].
Il compagno ha risposto correttamente a [n/4] domande di verifica.
Ho aggiornato queste sezioni in base al feedback: [lista].
Il README ora descrive il progetto com'è oggi, non com'era settimane fa.

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