Scrivere decisioni tecniche e trade-off

Questa lezione appartiene al Modulo 23 — Preparazione della consegna finale estesa.

Cos’è un trade-off

Un trade-off è una scelta che porta vantaggi in una direzione e svantaggi in un’altra. Non esiste una scelta tecnica senza trade-off — esistono solo scelte con trade-off non dichiarati.

Esempi dal Registro del laboratorio:

• localStorage è semplice da usare ma non è condiviso tra utenti
• separare dominio da infrastruttura rende il codice testabile ma aggiunge file e indirezione
• usare errori con codici (STRUMENTO_NON_TROVATO) è preciso ma richiede un dizionario in Presentation
• un archivio in memoria è perfetto per i test ma i dati si perdono al reload

Una decisione tecnica ben documentata dichiara esplicitamente il trade-off — non nasconde lo svantaggio.

Il formato per scrivere una decisione tecnica

## Decisione: [nome breve della scelta]

**Problema:** [cosa stava succedendo che ha reso necessaria la decisione]

**Opzioni considerate:**
- [opzione A]: [vantaggi e svantaggi]
- [opzione B]: [vantaggi e svantaggi]

**Scelta:** [opzione scelta]

**Motivazione:** [perché questa opzione rispetto alle altre]

**Trade-off accettato:** [cosa si perde con questa scelta]

**Conseguenze:** [cosa diventa più facile, cosa diventa più difficile]

Non serve scrivere tutto per ogni decisione. Per le decisioni minori, bastano Problema, Scelta, Trade-off.

Tre decisioni tecniche del Registro — compilate

Decisione 1: localStorage come persistenza

## Decisione: localStorage come unica persistenza

**Problema:** il Registro deve salvare dati tra una sessione e l'altra, senza un server.

**Opzioni considerate:**
- localStorage: built-in nel browser, zero setup. Dati per-browser, non condivisibili.
- SQLite: transazioni reali, dati persistenti. Richiede Node.js — non funziona nel browser direttamente.
- API + database: dati condivisi, multi-utente. Richiede un server e backend separato.

**Scelta:** localStorage

**Motivazione:** il contesto è un laboratorio scolastico con un solo utente alla volta.
                 Non serve condivisione tra dispositivi. Il setup zero è un vantaggio reale.

**Trade-off accettato:** i dati si perdono se si cancella la cache del browser.
                         Non è possibile condividere il registro tra più computer.

**Conseguenze:** l'adapter localStorage è sostituibile con un adapter API in futuro —
                 cambierebbe solo infrastructure/, non il dominio né i casi d'uso.

Decisione 2: dominio separato dall’infrastruttura

## Decisione: dominio senza dipendenze da localStorage

**Problema:** i test del dominio richiedevano un browser per girare,
              perché le funzioni chiamavano localStorage direttamente.

**Scelta:** le funzioni in domain/ non importano nulla di esterno.
            I casi d'uso ricevono l'archivio come dipendenza.

**Trade-off accettato:** ogni caso d'uso richiede una factory (creaRegistraPrestito)
                         invece di una funzione semplice. Aggiunge un livello di indirezione.

**Conseguenze:** i test del dominio girano con oggetti in memoria, senza browser.
                 Cambiare archivio richiede solo di modificare main.js.

Decisione 3: errori con codici invece di messaggi

## Decisione: errori come codici (STRUMENTO_NON_TROVATO)

**Problema:** il dominio doveva comunicare i fallimenti alla Presentation senza
              conoscere il testo dei messaggi o la lingua dell'interfaccia.

**Scelta:** il dominio lancia errori con codici (`STRUMENTO_NON_TROVATO`).
            La Presentation traduce i codici in messaggi per l'utente.

**Trade-off accettato:** la Presentation deve mantenere un dizionario di traduzione.
                         Se si aggiunge un nuovo codice errore, il dizionario va aggiornato.

**Conseguenze:** cambiare il testo di un messaggio non richiede di toccare il dominio.
                 La stessa base di codice può supportare più lingue cambiando solo il dizionario.

Quante decisioni documentare

Non bisogna documentare ogni scelta. Tre-cinque decisioni ben scritte sono più utili di venti superficiali.

Documenta le decisioni che:

• qualcuno potrebbe voler cambiare in futuro
• non sono ovvie dalla struttura del codice
• hanno un trade-off significativo da dichiarare

Non documentare:

• scelte ovvie senza alternative reali
• scelte che si vede direttamente dal codice
• scelte temporanee che sai già di voler cambiare

Dove mettere le decisioni

Tre opzioni:

1. Sezione nel README — ## Decisioni tecniche con le tre decisioni principali
2. File separato — docs/decisioni.md se ci sono molte decisioni
3. Commento nel file — per decisioni che riguardano un singolo file specifico

Per il Registro del laboratorio, la sezione nel README è sufficiente.

Procedura guidata

1. Elenca le cinque scelte tecniche più importanti del tuo Registro.
2. Per ognuna: quale problema risolveva? Quali alternative esistevano?
3. Scegli tre da documentare — quelle con trade-off più interessanti.
4. Scrivi il formato breve (Problema, Scelta, Trade-off) per ognuna.
5. Aggiungi la sezione al README.

Attività in classe

## Decisioni tecniche da documentare

Decisione 1:
  - Problema:
  - Opzioni considerate:
  - Scelta:
  - Trade-off accettato:

Decisione 2:
  - Problema:
  - Scelta:
  - Trade-off accettato:

Decisione 3:
  - Problema:
  - Scelta:
  - Trade-off accettato:

Dove sono state aggiunte nel progetto:

Spiegazione guidata per studiare

Documentare le decisioni tecniche non è un esercizio accademico — è una forma di rispetto per chi lavora sul progetto in futuro (incluso te stesso). Senza la documentazione delle decisioni, chi arriva dopo non sa perché il codice è strutturato in un certo modo e potrebbe “correggere” una scelta deliberata.

Il punto centrale è: il trade-off dichiarato trasforma una scelta da “così è capitato” a “così è stato deciso”. La differenza è enorme per la manutenibilità.

Il rischio tipico è documentare solo il vantaggio di una scelta e nascondere lo svantaggio. Una decisione tecnica onesta nomina entrambi — e spiega perché il vantaggio valeva lo svantaggio nel contesto specifico.

Passo per passo nel progetto

1. Apri il README del tuo Registro — ha una sezione “Decisioni tecniche”?
2. Se no: aggiungi la sezione e scrivi la prima decisione (localStorage).
3. Scrivi il trade-off esplicitamente — “accettiamo che i dati si perdono perché…”
4. Aggiungi altre due decisioni con lo stesso formato.
5. Verifica che ogni decisione risponda a: perché questa scelta rispetto alle alternative?

Esempio da leggere lentamente

Decisione mal scritta:
"Usiamo localStorage perché è semplice."

Decisione ben scritta:
"Usiamo localStorage perché non abbiamo un server e il laboratorio ha un solo utente
alla volta. Accettiamo che i dati si perdano se si cancella la cache del browser e
che non sia possibile condividere il registro tra dispositivi. Se il laboratorio
crescesse a più utenti contemporanei, sostituiremmo localStorage con un'API —
cambiando solo infrastructure/, non dominio e casi d'uso."

La seconda versione:
- nomina il problema che ha guidato la scelta
- dichiara il trade-off
- indica la via d'uscita per un futuro cambiamento

Prova di comprensione

• Riesci a elencare tre decisioni tecniche del tuo Registro con il relativo trade-off?
• Il trade-off di ogni decisione è dichiarato esplicitamente o nascosto?
• Chi legge le decisioni nel README capisce perché hai scelto localStorage invece di SQLite?

Errori da evitare

• documentare solo i vantaggi di una scelta — il trade-off è la parte più utile;
• scrivere decisioni ovvie che non hanno alternative reali;
• usare gergo tecnico senza spiegarlo — le decisioni devono essere leggibili anche tra sei mesi;
• non aggiornare le decisioni quando cambiano (una decisione obsoleta è peggio di nessuna decisione).

Prodotto da consegnare

Può essere:

• una sezione “Decisioni tecniche” nel README con tre decisioni nel formato completo;
• un file docs/decisioni.md con le stesse decisioni;
• una scheda compilata con problema, scelta e trade-off per tre decisioni.

Checklist di chiusura

• Ho identificato almeno tre decisioni tecniche significative del mio Registro
• Ogni decisione dichiara esplicitamente il trade-off accettato
• Le decisioni sono scritte in linguaggio comprensibile (non solo gergo tecnico)
• Le decisioni sono aggiunte al README o a un file dedicato
• Ogni decisione risponde alla domanda “perché questa scelta rispetto alle alternative?”

Domande per la revisione

• Le decisioni che hai scritto includono alternative considerate?
• Il trade-off di ogni decisione è onesto o nasconde gli svantaggi?
• Un compagno che non conosce il progetto capisce le decisioni senza spiegazioni aggiuntive?

Risultato atteso

Alla fine lo studente deve saper dire:

Ho documentato queste tre decisioni tecniche nel README:
1. [Nome decisione]: ho scelto [X] perché [motivo] — il trade-off è [svantaggio].
2. [Nome decisione]: ho scelto [X] perché [motivo] — il trade-off è [svantaggio].
3. [Nome decisione]: ho scelto [X] perché [motivo] — il trade-off è [svantaggio].

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