Consegna finale: review, rubric e roadmap

La consegna finale non è solo “ecco il codice”.

Deve comunicare:

• cosa fa il progetto;
• come si avvia;
• quali scelte sono state fatte;
• cosa è testato;
• quali limiti restano;
• cosa faresti dopo.

Questa lezione chiude il corso con una review strutturata.

Pacchetto di consegna

La consegna ideale contiene:

README.md
PROJECT.md
Package.swift
Sources/
Tests/
Docs o .docc/

README:

• descrizione breve;
• requisiti;
• comandi;
• architettura;
• demo;
• test;
• limiti;
• roadmap.

Demo script

Scrivi uno script umano della demo.

Esempio CLI:

swift run story search "swift concurrency"
swift run story search "swift concurrency" --json
swift test

Esempio SwiftUI:

1. Avvia app
2. Cerca "swift"
3. Mostra loading
4. Mostra risultati
5. Disattiva rete o usa fake failure
6. Mostra messaggio errore/cache

Una demo preparata evita improvvisazione fragile.

Checklist tecnica

Prima della consegna:

swift build
swift test
swift build -c release

Se usi tool aggiuntivi:

swift format lint --recursive Sources Tests
swift package generate-documentation

Non includere comandi che non hai verificato.

Review architetturale

Controlla:

• il dominio importa solo ciò che serve;
• la UI non decodifica JSON;
• i repository sono dietro protocolli;
• gli errori sono significativi;
• la cache è sostituibile;
• la rete non appare nei test unitari;
• le dipendenze sono iniettate;
• Sendable e actor sono usati dove servono;
• non ci sono singleton nascosti.

Review API

Per ogni tipo pubblico:

Nome:
Responsabilità:
Perché è public:
Errori:
Esempio d'uso:
Test:

Se non sai compilare questa scheda, forse il tipo non deve essere pubblico o non è abbastanza chiaro.

Rubric di valutazione

Valuta il progetto su 5 aree.

1. Dominio

Ottimo:

• tipi ricchi;
• invarianti nei costruttori;
• errori espliciti;
• pochi stati impossibili.

Debole:

• tutto String e Int;
• regole sparse;
• optional usati come errori;
• nomi generici.

2. Architettura

Ottimo:

• confini chiari;
• dipendenze iniettate;
• infrastruttura ai bordi;
• use case leggibili.

Debole:

• UI o CLI chiamano direttamente rete;
• DTO nel dominio;
• singleton;
• service enormi.

3. Concurrency e resilienza

Ottimo:

• cancellation rispettata;
• retry ragionato;
• actor per stato condiviso;
• errori non mascherati.

Debole:

• Task {} non osservati;
• sleep arbitrari;
• cancellation convertita in errore generico;
• stato mutabile condiviso.

4. Test

Ottimo:

• test dominio;
• test use case;
• test mapping;
• test async;
• test errori/cache;
• nessuna rete reale.

Debole:

• solo percorso felice;
• test lenti;
• test fragili;
• setup enorme.

5. Consegna

Ottimo:

• README chiaro;
• demo breve;
• comandi verificati;
• DocC o documentazione;
• roadmap realistica.

Debole:

• istruzioni mancanti;
• impossibile avviare;
• nessuna spiegazione delle scelte.

Rischi residui

Ogni progetto reale ha limiti.

Scrivili:

## Limiti

- La cache è in memoria e si perde al riavvio.
- Il retry usa una policy semplice.
- L'API remota non richiede autenticazione.
- La UI non include paginazione avanzata.

Non è un’ammissione di fallimento. È maturità tecnica.

Roadmap

Roadmap utile:

## Roadmap

1. Cache persistente con scadenza
2. Paginazione
3. Metriche e logging
4. UI dettaglio
5. CI su macOS e Linux

Evita roadmap vaghe come “migliorare tutto”.

Retrospettiva

Chiudi con tre domande:

Cosa ha funzionato bene?
Cosa rifaresti diversamente?
Quale scelta tecnica è stata più importante?

Questa parte trasforma il progetto in apprendimento trasferibile.

Checklist finale

Consegna solo quando:

• build passa;
• test passano;
• demo è ripetibile;
• README è aggiornato;
• PROJECT.md riflette il risultato;
• errori principali sono gestiti;
• codice morto rimosso;
• TODO critici risolti o documentati;
• roadmap scritta;
• limiti dichiarati.

Esercizio finale

Prepara una review del tuo progetto in questo formato:

# Final Review

## Demo

## Architecture

## What is tested

## Key tradeoffs

## Known limitations

## Roadmap

Poi fai una passata come reviewer:

1. trova un rischio architetturale;
2. trova un test mancante;
3. trova un nome migliorabile;
4. trova una dipendenza nascosta;
5. trova una parte da documentare meglio.

Obiettivo: chi finisce questo corso non deve solo aver costruito qualcosa. Deve saperlo valutare.