Scrivere una decisione tecnica breve

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

La regola delle tre frasi

Una decisione tecnica breve risponde a tre domande in tre frasi:

1. Problema: cosa succedeva che richiedeva una scelta?
2. Scelta: cosa hai deciso di fare?
3. Trade-off: cosa perdi con questa scelta?

Non serve altro. Una decisione di sei righe è meglio di una di sei paragrafi.

Il formato minimo

**[Nome della decisione]**

Problema: [una frase che descrive la situazione prima della scelta].
Scelta: [una frase che descrive cosa hai fatto].
Trade-off: [una frase che descrive cosa hai perso o accettato].

Questo formato occupa quattro righe. È sufficiente per documentare la maggior parte delle decisioni tecniche di un progetto come il Registro del laboratorio.

Esercizio: da frase vaga a decisione tecnica

Le frasi vaghe non comunicano nulla. Questo esercizio trasforma frasi vaghe in decisioni tecniche utili.

---

Frase vaga 1: “Abbiamo usato localStorage.”

Manca: perché, alternativa, trade-off.

Decisione tecnica breve:

Problema: il Registro deve salvare dati tra sessioni senza un server.
Scelta: localStorage — integrato nel browser, zero setup.
Trade-off: i dati si perdono se si cancella la cache; non condivisibili tra dispositivi.

---

Frase vaga 2: “Il dominio non conosce localStorage.”

Manca: perché questa scelta, cosa rende possibile.

Decisione tecnica breve:

Problema: testare le regole del dominio richiedeva un browser aperto.
Scelta: le funzioni in domain/ non importano localStorage; ricevono l'archivio come parametro.
Trade-off: ogni caso d'uso richiede una factory invece di una funzione semplice.

---

Frase vaga 3: “Usiamo errori con codici.”

Manca: perché non messaggi diretti, chi traduce.

Decisione tecnica breve:

Problema: il dominio non doveva conoscere il testo dei messaggi per l'utente.
Scelta: il dominio lancia errori con codici (STRUMENTO_NON_TROVATO); la Presentation traduce.
Trade-off: la Presentation deve mantenere un dizionario — ogni nuovo codice va aggiunto.

---

Come scrivere la tua decisione tecnica breve

Segui questi tre passi nell’ordine:

Passo 1 — scrivi il problema partendo dal sintomo, non dalla soluzione:

❌ "Problema: volevamo testare senza browser."
   → è una soluzione camuffata da problema

✅ "Problema: ogni test del dominio richiedeva un browser aperto per accedere a localStorage."
   → è il sintomo concreto che ha reso necessaria la scelta

Passo 2 — scrivi la scelta in modo verificabile:

❌ "Scelta: abbiamo separato le responsabilità."
   → vago, non verificabile

✅ "Scelta: le funzioni in domain/strumento.js non importano nulla di esterno."
   → chi arriva può verificare aprendo il file

Passo 3 — nomina il trade-off onestamente:

❌ "Trade-off: nessuno."
   → ogni scelta ha un trade-off; "nessuno" significa che non è stato trovato

✅ "Trade-off: ogni caso d'uso richiede una factory — più codice da scrivere e da capire."
   → onesto e specifico

Esercizio in classe

Scrivi una decisione tecnica breve per una scelta del tuo Registro che ancora non hai documentato. Poi scambia con un compagno e verifica:

• Il problema descrive un sintomo concreto (non una soluzione)?
• La scelta è verificabile aprendo un file?
• Il trade-off è onesto o nasconde qualcosa?

Attività in classe

## Decisione tecnica breve

Scelta da documentare: [nome]

Bozza:
  Problema: 
  Scelta: 
  Trade-off: 

Feedback del compagno:
  - Il problema era chiaro (sì/no)?
  - La scelta era verificabile (sì/no)?
  - Il trade-off era onesto (sì/no)?

Versione finale:
  Problema: 
  Scelta: 
  Trade-off: 

Spiegazione guidata per studiare

Una decisione tecnica breve è la forma minima di documentazione che ha valore a lungo termine. Non sostituisce il codice — lo integra spiegando il “perché” che il codice non può comunicare da solo.

Il punto centrale è: la brevità non è limitazione — è disciplina. Scrivere in tre frasi forza a chiarire il ragionamento. Se non riesci a scrivere il problema in una frase, probabilmente non hai ancora capito bene quale problema stai risolvendo.

Il rischio tipico è scrivere il problema come “volevamo fare X” invece di “X causava Y”. Il problema deve descrivere una situazione concreta — un dolore, un limite, un vincolo — non l’intenzione.

Passo per passo nel progetto

1. Scegli una scelta del Registro che ancora non hai documentato.
2. Scrivi il problema in una frase — cosa succedeva prima della scelta?
3. Scrivi la scelta in una frase — cosa hai fatto di concreto?
4. Scrivi il trade-off in una frase — cosa hai perso o accettato?
5. Leggi le tre frasi: rispondono alla domanda “perché il codice è strutturato così?”
6. Aggiungi le tre frasi al README nella sezione “Decisioni tecniche”.

Esempio da leggere lentamente

Decisione troppo lunga (evita):

"Abbiamo deciso di usare il pattern della dependency injection per i casi d'uso
 del Registro del laboratorio scolastico perché questo ci permetteva di separare
 la logica di business dall'infrastruttura concreta, rendendo così possibile
 scrivere test unitari che non dipendessero da localStorage o da altri sistemi
 di persistenza. Questo approccio è stato ispirato dai principi di clean
 architecture e SOLID, in particolare dall'Dependency Inversion Principle..."

Decisione breve (usa):

Problema: i test del dominio richiedevano localStorage — impossibile testarli senza browser.
Scelta: i casi d'uso ricevono l'archivio come parametro (dependency injection manuale).
Trade-off: ogni caso d'uso richiede una factory — più setup in main.js.

La versione breve dice tutto l’essenziale in tre righe.

Prova di comprensione

• Il problema della tua decisione descrive un sintomo concreto o un’intenzione?
• La scelta è verificabile aprendo un file del tuo progetto?
• Il trade-off nomina qualcosa di reale che hai perso?

Errori da evitare

• scrivere il problema come intenzione (“volevamo…”) invece che come sintomo (“succedeva che…”);
• rendere la scelta non verificabile (“abbiamo separato le responsabilità”);
• dire “nessun trade-off” — ogni scelta ha un costo, anche piccolo;
• scrivere più di tre-quattro frasi per decisione — se serve di più, usa il formato completo della lezione 151.

Prodotto da consegnare

Può essere:

• una decisione tecnica breve aggiunta al README (tre righe: problema, scelta, trade-off);
• la scheda compilata con bozza, feedback e versione finale;
• tre decisioni brevi per il Registro, ognuna verificata da un compagno.

Checklist di chiusura

• Ho scritto almeno una decisione tecnica breve con le tre componenti
• Il problema descrive un sintomo concreto (non un’intenzione)
• La scelta è verificabile aprendo un file del progetto
• Il trade-off è onesto e specifico
• La decisione è stata letta da un compagno e compresa senza spiegazioni

Domande per la revisione

• Il compagno ha capito la decisione senza che tu spiegassi nulla?
• Se no, quale delle tre frasi era poco chiara?
• Hai trovato difficile scrivere il trade-off? Perché?

Risultato atteso

Alla fine lo studente deve saper dire:

Ho scritto questa decisione tecnica breve:
Problema: [una frase — sintomo concreto].
Scelta: [una frase — azione verificabile].
Trade-off: [una frase — costo onesto].
È nel README nella sezione "Decisioni tecniche".

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