Preparare README e mappa del progetto

Un progetto che funziona ma non si capisce resta fragile.

Il README non deve essere lungo.

Deve permettere a un compagno, a un docente o a te stesso tra una settimana di capire:

• che cosa fa il progetto;
• come e organizzato;
• dove sono le regole;
• come si avvia;
• quali parti sono ancora semplici.

Obiettivo

Alla fine devi avere:

• README aggiornato;
• mappa dei livelli;
• elenco delle funzionalita essenziali;
• elenco dei test o scenari;
• note sui limiti della versione a 20 ore.

Struttura minima del README

Usa questa traccia:

# Registro del laboratorio scolastico

## Obiettivo

## Funzionalita essenziali

## Struttura del progetto

## Livelli architetturali

## Come avviare il progetto

## Regole principali

## Test o scenari di verifica

## Limiti della versione essenziale

## Prossimi miglioramenti

Non serve scrivere un trattato.

Ogni sezione deve aiutare a orientarsi.

Obiettivo

Esempio:

## Obiettivo

Il progetto realizza un registro del laboratorio scolastico.
Permette di registrare strumenti, cercarli, prestare strumenti disponibili,
chiudere prestiti e segnalare guasti.

Questa sezione deve essere breve.

Funzionalita essenziali

Esempio:

## Funzionalita essenziali

- registrare strumenti;
- cercare strumenti per nome, categoria o stato;
- registrare un prestito;
- chiudere un prestito;
- aprire una segnalazione di guasto;
- mostrare messaggi comprensibili;
- salvare dati in memoria nella versione essenziale.

Questa lista deve corrispondere a quello che esiste davvero.

Non promettere funzionalita future come se fossero gia pronte.

Struttura del progetto

Esempio:

## Struttura del progetto

src/
  domain/
    strumento.js
    statoStrumento.js
    prestito.js
  application/
    registraStrumento.js
    cercaStrumenti.js
    registraPrestito.js
  infrastructure/
    archivioStrumentiInMemoria.js
    archivioPrestitiInMemoria.js
  presentation/
    uiRegistro.js

Questa mappa deve rispecchiare il tuo progetto reale.

Se un file non esiste, non inventarlo nel README.

Livelli architetturali

Scrivi una spiegazione breve:

## Livelli architetturali

- Domain: contiene modelli e regole del laboratorio.
- Application: contiene i casi d'uso che coordinano le operazioni.
- Infrastructure: contiene archivi e salvataggio dati.
- Presentation: contiene UI, lettura input e messaggi.

Poi aggiungi un esempio:

Esempio: RegistraPrestito sta in Application.
Chiama il dominio per verificare se lo strumento e prestabile
e usa gli archivi per salvare prestito e strumento aggiornato.

Regole principali

Esempio:

## Regole principali

- uno strumento senza nome non e valido;
- solo uno strumento disponibile puo essere prestato;
- uno strumento guasto non puo essere prestato;
- uno strumento in manutenzione non puo essere prestato;
- un prestito chiuso non puo essere chiuso di nuovo.

Questa sezione aiuta a capire il dominio.

Test o scenari

Esempio:

## Test o scenari di verifica

- strumento senza nome -> errore;
- strumento guasto -> prestito rifiutato;
- prestito chiuso -> seconda chiusura rifiutata;
- registrazione prestito valida -> prestito aperto e strumento in_prestito.

Se hai comandi per eseguire test, scrivili.

Se hai solo scenari manuali, dichiaralo.

Limiti della versione essenziale

Questa sezione e importante.

Esempio:

## Limiti della versione essenziale

- i dati sono salvati solo in memoria;
- al refresh della pagina i dati si perdono;
- non ci sono login o ruoli completi;
- non esiste ancora una API;
- la documentazione e minima;
- i test coprono solo le regole principali.

Dire i limiti non indebolisce il progetto.

Lo rende onesto e comprensibile.

Mappa del flusso

Inserisci una mappa testuale:

## Flusso RegistraPrestito

UI
  crea comando
Application
  trova strumento
  verifica regole
  crea prestito
  salva modifiche
Domain
  controlla prestabilita
  crea prestito valido
Infrastructure
  conserva strumenti e prestiti in memoria

E sufficiente.

Non serve UML complesso.

Esercizio

Aggiorna il README e poi fallo leggere a un compagno.

Il compagno deve rispondere:

• che cosa fa il progetto?
• dove sono le regole?
• dove sono i casi d’uso?
• dove sono gli archivi?
• quali sono i limiti?

Se non riesce a rispondere, il README va migliorato.

Cosa produrre

Alla fine della lezione devi avere:

• README aggiornato;
• mappa delle cartelle;
• spiegazione dei quattro livelli;
• lista delle regole principali;
• lista dei limiti della versione essenziale;
• almeno un flusso descritto.

Spiegazione guidata per studiare

Questa lezione va studiata su due piani. Il primo è il comportamento visibile del Registro del laboratorio: che cosa vede o fa l’utente quando registra uno strumento, cerca un dispositivo, apre un prestito o segnala un guasto. Il secondo è il confine architetturale: dove deve stare il codice che rende possibile quel comportamento.

Per preparare README e mappa del progetto, il punto centrale è questo: Documentare significa rendere esplicito il ragionamento: struttura del progetto, comandi, confini, scelte e limiti. Non è decorazione finale.

Il rischio tipico è scrivere documentazione generica che non corrisponde al codice. Una buona nota tecnica deve aiutare una persona reale a orientarsi. Per evitarlo, non partire dal file che hai già aperto nell’editor. Parti dalla domanda: “quale responsabilità sto modificando?”. Se la risposta riguarda una regola del laboratorio, guarda il dominio. Se riguarda una sequenza di operazioni, guarda i casi d’uso. Se riguarda salvataggio, file, localStorage, API o database, guarda l’infrastruttura. Se riguarda input, pulsanti, form e messaggi, guarda la Presentation.

Il tempo è sufficiente per alternare spiegazione, modifica guidata e revisione. Alla fine della lezione lo studente non deve ricordare una definizione a memoria: deve saper indicare un punto del progetto, spiegare perché quel codice sta lì e mostrare una verifica del comportamento.

Passo per passo nel progetto

1. Rileggi il titolo della lezione e riscrivilo come domanda pratica. Per esempio: “dove deve stare questa regola?”, “chi deve salvare questo dato?”, “come verifico questo errore?”.
2. Apri solo i file necessari. Se devi toccare più di tre file, fermati e scrivi prima una mini-mappa.
3. Descrivi il problema pratico.
4. Spiega la scelta fatta.
5. Indica l’effetto sul progetto.
6. Nomina almeno un limite o una alternativa.
7. Aggiorna una nota breve nel README o negli appunti se hai cambiato un confine del progetto.

Esempio da leggere lentamente

Questo esempio serve a ragionare, non a incollare codice senza capire:

## Decisione tecnica

Abbiamo tenuto il dominio separato da localStorage perché vogliamo poter
sostituire la persistenza senza riscrivere le regole sui prestiti.

Leggilo chiedendoti che cosa cambierebbe se domani sostituissimo la pagina web con una CLI, oppure localStorage con un’API. Se l’esempio continua ad avere senso senza riscrivere tutto, il confine è probabilmente buono. Se invece un dettaglio tecnico si propaga in molti file, il progetto sta tornando fragile.

Prova di comprensione

Prima di chiudere la lezione, rispondi per iscritto a queste domande:

• Qual è la responsabilità principale trattata in questa lezione?
• In quale livello del progetto dovrebbe stare?
• Quale errore faresti se cercassi la soluzione più veloce?
• Quale piccolo test, controllo manuale o esempio dimostra che hai capito?
• Che cosa deve restare facile da cambiare dopo questa lezione?

Una risposta accettabile non deve essere lunga. Deve però usare parole concrete del Registro: strumento, prestito, stato, archivio, caso d’uso, messaggio, test.

Controllo finale

La lezione e completata quando puoi rispondere si:

• il README spiega cosa fa il progetto;
• il README spiega dove sono i livelli;
• il README dichiara i limiti;
• una persona esterna puo orientarsi;
• la documentazione non promette cose non ancora fatte.

Nella prossima lezione facciamo la revisione del checkpoint 20 ore.