Documentare problemi incontrati

Questa lezione appartiene al Modulo 23 — Revisione finale.

Il lavoro continua il progetto guida, il Registro del laboratorio scolastico. In questa lezione documenti i problemi reali che hai incontrato durante lo sviluppo, in un formato che sia utile a te in futuro e comprensibile al docente.

Obiettivo della lezione

Documentare almeno tre problemi incontrati durante lo sviluppo del Registro usando il formato strutturato: problema — causa — soluzione — lezione appresa. La documentazione deve essere specifica, non generica.

Alla fine devi avere: una sezione “Problemi incontrati” nel README (o in un file separato PROBLEMI.md) con almeno tre voci compilate.

Perché documentare i problemi

Un problema risolto ma non documentato è un’opportunità persa. La prossima volta che incontri lo stesso tipo di problema — o quando qualcuno legge il tuo progetto — non c’è modo di capire cosa è andato storto e come è stato risolto.

Documentare i problemi ha tre utilità concrete:

• ti aiuta a ragionare sulla causa reale invece di fermarti alla soluzione
• mostra al docente che il progetto è stato sviluppato con consapevolezza, non per tentativi
• costruisce un catalogo personale di soluzioni a problemi reali

Il formato strutturato

Per ogni problema, usa questa struttura:

• Problema — cosa non funzionava, in termini osservabili (errore in console, comportamento sbagliato della UI, test che falliva)
• Causa — perché non funzionava (dipendenza sbagliata, dato null non gestito, chiave localStorage diversa)
• Soluzione — cosa hai fatto per risolverlo (specifica, con il file e la funzione modificata)
• Lezione appresa — cosa faresti diversamente la prossima volta, o cosa hai capito che non sapevi prima

Procedura guidata

1. Pensa agli ultimi tre problemi che ti hanno bloccato più di 15 minuti durante lo sviluppo.
2. Per ognuno, compila il formato strutturato.
3. Sii specifico — indica il file, la funzione, il messaggio di errore.
4. Inserisci la documentazione nel README in una sezione “Problemi incontrati”.
5. Se hai risolto il problema in modo non ideale (workaround), documentalo esplicitamente.

Attività in classe

Prima di scrivere, fai brainstorming con un compagno: elenca tutti i problemi che ricordi di aver incontrato. Poi seleziona i tre più significativi e compilane la documentazione.

## Brainstorming problemi incontrati

Problema 1 (una riga):
Problema 2:
Problema 3:
Problema 4:
Problema 5:

I tre più significativi da documentare: 1, _, _

Spiegazione guidata per studiare

Il formato “problema — causa — soluzione — lezione appresa” è deliberato. La parte più importante è la causa: non “l’ho risolto” ma “capisco perché succedeva”. Un problema risolto per tentativi senza capire la causa è pericoloso — si ripresenta in forme leggermente diverse che non riconosci.

La lezione appresa è la parte più difficile da scrivere. Deve essere specifica e azionabile: non “devo stare più attento”, ma “la prossima volta controllo le chiavi di localStorage prima di cercare bug nel codice”.

Passo per passo nel progetto

Ecco tre esempi reali di problemi tipici nel Registro, con il formato compilato:

Problema 1: i dati scompaiono dopo il reload

Problema:
Dopo aver registrato uno strumento e aver ricaricato la pagina,
la lista degli strumenti era vuota.

Causa:
La funzione salva() usava la chiave "strumenti" in localStorage.setItem,
ma caricaTutti() leggeva dalla chiave "registro_strumenti".
Le due chiavi erano diverse — i dati venivano scritti in un posto
e letti da un altro.

Soluzione:
Ho estratto la chiave in una costante condivisa:
  const CHIAVE = "registro_strumenti";
  usata sia in salva() che in caricaTutti().

File modificato: src/infrastructure/archivioStrumentiLocalStorage.js

Lezione appresa:
Le chiavi di localStorage non devono essere stringhe letterali ripetute.
La prossima volta definisco la costante subito, all'inizio del file.

Problema 2: apriPrestito non aggiorna lo stato dello strumento

Problema:
Dopo aver aperto un prestito, lo strumento continuava ad apparire
"disponibile" nella lista. Il prestito veniva creato in localStorage
ma lo stato dello strumento non cambiava.

Causa:
In apriPrestito, modificavo l'oggetto strumento trovato con find(),
ma salvavo un array diverso — quello originale caricato all'inizio
della funzione, prima della modifica.
Stavo modificando una copia dell'oggetto, non quello nell'array.

Soluzione:
Ho verificato che la modifica avvenisse sull'oggetto nell'array
originale (find restituisce un riferimento, non una copia, in JS).
Il bug reale era che stavo chiamando caricaTutti() una seconda volta
dopo la modifica, sovrascrivendo l'array già aggiornato.

File modificato: src/application/apriPrestito.js

Lezione appresa:
Array.find() in JavaScript restituisce un riferimento all'oggetto —
modificare l'oggetto trovato modifica anche l'array.
Ma se chiami caricaTutti() di nuovo, ottieni una nuova copia dal localStorage
e perdi le modifiche in memoria. Una sola lettura per operazione.

Problema 3: JSON.parse(null) non lancia errore ma produce null

Problema:
L'applicazione si bloccava con "Cannot read properties of null (reading 'map')"
alla prima apertura, quando localStorage era vuoto.

Causa:
localStorage.getItem("registro_strumenti") restituisce null quando la chiave
non esiste (non lancia un errore). JSON.parse(null) restituisce null (non lancia errore).
Poi null.map(...) lancia un errore.

Soluzione:
Ho aggiunto il controllo:
  const raw = localStorage.getItem("registro_strumenti");
  if (!raw) return [];
  return JSON.parse(raw).map(dtoToStrumento);

File modificato: src/infrastructure/archivioStrumentiLocalStorage.js — funzione caricaTutti

Lezione appresa:
localStorage.getItem e JSON.parse non lanciano errori nei casi null/vuoto.
Bisogna sempre verificare il valore prima di usarlo.

1. Inserisci la sezione nel README:

## Problemi incontrati durante lo sviluppo

[Problema 1]
Problema: ...
Causa: ...
Soluzione: ...
Lezione appresa: ...

[Problema 2]
...

Esempio JS — il codice prima e dopo il Problema 3

// PRIMA — crasha alla prima apertura con localStorage vuoto
export function caricaTutti() {
  return JSON.parse(localStorage.getItem("registro_strumenti")).map(dtoToStrumento);
  // TypeError: Cannot read properties of null (reading 'map')
}

// DOPO — gestisce il caso vuoto
export function caricaTutti() {
  const raw = localStorage.getItem("registro_strumenti");
  if (!raw) return [];
  return JSON.parse(raw).map(dtoToStrumento);
}

Prova di comprensione

Rispondi per iscritto:

• Qual è il problema che ti ha bloccato più a lungo durante lo sviluppo? Qual era la causa reale?
• C’è un problema che hai “risolto” senza capire veramente la causa? Come lo documenteresti?
• Qual è la lezione appresa più utile che porteresti in un progetto futuro?
• Guardando i tre esempi sopra, hai incontrato almeno uno di questi problemi nel tuo Registro?

Errori da evitare

• scrivere “Problema: non funzionava” senza indicare cosa non funzionava esattamente;
• scrivere “Soluzione: ho fixato il bug” senza indicare il file e la riga modificata;
• omettere la causa — è la parte più utile;
• documentare solo i problemi risolti perfettamente, non i workaround.

Prodotto da consegnare

La sezione “Problemi incontrati” nel README con almeno tre voci nel formato strutturato. Come verifica: il docente deve poter capire il problema, la causa e la soluzione senza chiedere spiegazioni aggiuntive.

Checklist di chiusura

• almeno tre problemi sono documentati con il formato completo;
• ogni voce indica il file e la funzione modificata;
• la causa è separata dalla soluzione;
• la lezione appresa è specifica e azionabile;
• i workaround sono documentati come tali, non presentati come soluzioni ideali.

Risultato atteso

Ho documentato tre problemi incontrati durante lo sviluppo del Registro.
Il più importante era: [descrizione in una riga].
La causa era: [spiegazione tecnica].
La lezione appresa: [frase specifica e azionabile].
La documentazione è nella sezione "Problemi incontrati" del README.