Documentare comandi, test e dati di esempio

Questa lezione appartiene al Modulo 15 — Documentazione.

Il lavoro continua il progetto guida, il Registro del laboratorio scolastico. In questa lezione scrivi le sezioni del README che documentano i comandi operativi: come avviare, come testare, come caricare i dati di esempio.

Obiettivo della lezione

Scrivere nel README le tre sezioni operative — “Come avviare”, “Come eseguire i test”, “Dati di esempio” — con comandi precisi e copiabili, verificati sul progetto reale.

Alla fine devi avere: un README con le tre sezioni complete, con comandi che funzionano su un computer nuovo senza modifiche.

Cosa rende un comando documentabile

Un comando documentato bene ha queste caratteristiche:

• è copiabile direttamente nel terminale senza modifiche
• indica da quale cartella deve essere eseguito
• produce un output riconoscibile (cosa deve apparire se va bene)
• ha una nota sul prerequisito (Node.js installato? Live Server attivo?)

Un comando documentato male: “avvia il server”. Un comando documentato bene: npx http-server . -p 8080 (eseguito dalla cartella root del progetto, richiede Node.js).

Nel Registro del laboratorio

I comandi principali da documentare per il Registro sono:

• avvio del server locale per servire index.html
• esecuzione dei test automatici con Node.js
• caricamento dei dati di esempio in localStorage

Procedura guidata

1. Apri il README del Registro.
2. Scrivi la sezione “Come avviare” con il comando esatto e i prerequisiti.
3. Scrivi la sezione “Come eseguire i test” con ogni comando su una riga separata.
4. Scrivi la sezione “Dati di esempio” con lo script da incollare in console.
5. Verifica ogni comando eseguendolo in un terminale pulito.
6. Per ogni comando che fallisce, correggi prima il comando, poi la documentazione.

Attività in classe

Compila questa scheda prima di scrivere il README:

## Comandi da documentare

Avvio del server locale:
Comando:
Prerequisiti:
Output atteso:

Esecuzione test:
Comando 1:
Comando 2:
Output atteso:

Caricamento dati di esempio:
Dove si esegue (console browser / terminale):
Script da incollare:
Output atteso:

Spiegazione guidata per studiare

La documentazione dei comandi è la parte del README che viene letta più spesso — e quella che diventa obsoleta più in fretta. Ogni volta che cambia un nome di file, un percorso o una dipendenza, i comandi devono essere aggiornati.

Il modo più semplice per tenerla aggiornata è verificarla alla fine di ogni sessione di lavoro importante: “se qualcuno esegue questi comandi adesso, funzionano?”. Se la risposta è “dipende”, la documentazione è già obsoleta.

Passo per passo nel progetto

1. Scrivi la sezione “Come avviare”:

## Come avviare

### Prerequisiti

- Node.js (versione 18 o successiva): https://nodejs.org
- Un browser moderno (Chrome, Firefox, Edge)

### Comandi

Dalla cartella root del progetto:

    npx http-server . -p 8080

Poi apri nel browser: http://localhost:8080

Alternativa con VS Code: installa l'estensione "Live Server",
click destro su index.html → Open with Live Server.

### Nota importante

Il progetto usa moduli ES6 e non funziona aprendo index.html
direttamente nel browser (protocollo file://). È necessario il server locale.

1. Scrivi la sezione “Come eseguire i test”:

## Come eseguire i test

I test non richiedono il browser — si eseguono con Node.js dal terminale.

Dalla cartella root del progetto:

    node src/test/test-casi-limite.js

    node src/test/test-con-dati-esempio.js

    node src/test/test-sostituzione-archivio.js

Output atteso: ogni riga inizia con "OK:" e alla fine non ci sono righe "FALLITO:".

Se un test fallisce, la riga "FALLITO:" indica quale test e quale errore.

1. Scrivi la sezione “Dati di esempio” nel README. Il contenuto della sezione deve spiegare i passi e includere lo script JS da incollare in console. Esempio di come appare nel README finito:

La sezione inizia con i passi (avvia, apri console, incolla lo script, ricarica) e contiene uno script JS con i dati iniziali e uno script per azzerare. Usa il formato di blocco codice con linguaggio js per entrambi gli script.

Lo script di caricamento dati da inserire nel README:

const strumenti = [
  { id: "str-001", name: "Multimetro digitale", category: "misura", status: "disponibile" },
  { id: "str-002", name: "Oscilloscopio 2 canali", category: "misura", status: "in-prestito" },
  { id: "str-003", name: "Saldatore a stazione", category: "saldatura", status: "disponibile" },
  { id: "str-004", name: "Trapano a colonna", category: "perforazione", status: "guasto" }
];
const prestiti = [
  { id: "pre-001", strumentoId: "str-002", dataApertura: "2025-10-01", dataChiusura: null }
];
localStorage.setItem("registro_strumenti", JSON.stringify(strumenti));
localStorage.setItem("registro_prestiti", JSON.stringify(prestiti));
console.log("Dati di esempio caricati.");

Lo script per azzerare i dati da inserire nel README:

localStorage.removeItem("registro_strumenti");
localStorage.removeItem("registro_prestiti");
console.log("Dati azzerati.");

1. Verifica ogni sezione eseguendo i comandi effettivamente. Non documentare comandi che non hai testato.

Esempio — struttura README operativo completo

# Registro del laboratorio scolastico

Sistema browser-only per la gestione degli strumenti del laboratorio.

## Come avviare

    npx http-server . -p 8080

Poi apri http://localhost:8080

## Come eseguire i test

    node src/test/test-casi-limite.js
    node src/test/test-con-dati-esempio.js

## Dati di esempio

Incolla in console (F12) e ricarica la pagina.

[script di caricamento]

## Struttura del progetto

src/domain/         — modelli e regole
src/application/    — casi d'uso
src/infrastructure/ — adapter localStorage
src/presentation/   — UI e gestori eventi
main.js             — punto di composizione

## Limiti noti

- Nessuna autenticazione — ruolo impostato in main.js
- Dati non sincronizzati tra schede diverse

Prova di comprensione

Rispondi per iscritto:

• Hai eseguito tutti i comandi documentati in un terminale pulito? Tutti funzionano?
• Perché è importante indicare da quale cartella va eseguito ogni comando?
• Qual è il comando per azzerare i dati in localStorage senza aprire DevTools?
• Se i test falliscono dopo il caricamento dei dati di esempio, dove cerchi il problema?

Errori da evitare

• documentare comandi che non hai mai eseguito (“dovrebbe funzionare così”);
• non indicare i prerequisiti (Node.js, versione, ecc.);
• copiare il README da un altro progetto senza adattare i comandi;
• non aggiornare la documentazione quando cambiano i percorsi dei file di test.

Prodotto da consegnare

Le tre sezioni del README — avvio, test, dati di esempio — complete e verificate. Come controllo finale: dai il README a un compagno e chiedigli di eseguire tutti i comandi senza il tuo aiuto. Conta quante volte si ferma.

Checklist di chiusura

• la sezione “Come avviare” ha il comando esatto e i prerequisiti;
• la sezione “Come eseguire i test” elenca tutti i file di test con il comando;
• la sezione “Dati di esempio” ha uno script copiabile e un comando per azzerare;
• ho eseguito ogni comando in un terminale pulito e funzionano;
• un compagno ha seguito le istruzioni senza aiuto.

Risultato atteso

Ho scritto le tre sezioni operative nel README.
Tutti i comandi sono stati testati in un terminale pulito.
Il compagno ha avviato il progetto ed eseguito i test senza chiedere aiuto.
I dati di esempio si caricano con lo script e rimangono dopo il reload.