Le domande da farsi
Cinque riquadri prima di scrivere una riga di codice
- 12 minuti di lettura
All'ufficio oggetti smarriti di Porta Codice lavora Nives Corti. Gli oggetti trovati sulla Linea Menta finiscono in scatoloni, con un cartellino scritto a mano. Chi ha perso un ombrello telefona dalle 9 alle 12, e Nives cerca a memoria. Dopo sessanta giorni gli oggetti non ritirati vanno in beneficenza, e nessuno lo sa.
Nives ti chiede un'app. Tu hai già tutto quello che serve per scriverla: Python, FastAPI, un database. Ma da dove si comincia?
Non si comincia dal codice. Si comincia da una pagina e da otto domande. Questo capitolo ne fa cinque.
Perché prima le domande
Cambiare un'idea costa meno quanto più sei vicino al foglio.
| Dove ti accorgi dell'errore | Cosa devi rifare |
|---|---|
| Sul foglio | Una riga cancellata. Un minuto |
| Nelle tabelle | Lo schema, i dati di prova, le query |
| Nelle rotte | Tutto quello che sta sopra le tabelle, e i test |
| Nell'interfaccia | Le schermate che usano quelle rotte |
| Quando qualcuno la usa già | Tutto, e il suo lavoro si rompe |
Cambiare un'idea sul foglio costa un minuto. Cambiare un database costa giorni. Per questo le domande vengono prima.
C'è un secondo motivo. Un'app che fa tutto non finisce mai: ogni funzione in più porta le sue tabelle, le sue rotte, le sue schermate, i suoi test. Il tempo è quello che è. Decidere subito cosa non fai è metà del lavoro.
Il canvas: l'app in una pagina
Chi progetta un programma comincia da un canvas: una pagina divisa in riquadri, uno per domanda. Il tuo ne ha otto. Lo hai già incontrato: in Disegnare un database hai usato i riquadri dei dati e delle azioni, e in Il contratto quelli delle azioni e di chi può fare cosa. Qui li compili tutti, uno alla volta.
┌───────────────────┬───────────────────┬───────────────────┐
│ 1 · La frase │ 2 · Per chi │ 3 · Il problema │
├───────────────────┼───────────────────┴───────────────────┤
│ 4 · Le funzioni │ 5 · Le schermate │
├───────────────────┼───────────────────┬───────────────────┤
│ 6 · I dati │ 7 · Le azioni │ 8 · Chi può │
│ │ │ fare cosa │
└───────────────────┴───────────────────┴───────────────────┘| Riquadro | La domanda | Dove |
|---|---|---|
| 1 · La frase | Cosa fa la tua app, in una frase? | Questo capitolo |
| 2 · Per chi | Chi la usa? | Questo capitolo |
| 3 · Il problema | Cosa fanno oggi, senza la tua app? | Questo capitolo |
| 4 · Le funzioni | Le 3 cose che deve saper fare | Questo capitolo |
| 5 · Le schermate | Quali pagine vede chi la usa? | Questo capitolo |
| 6 · I dati | Quali «cose» ricorda l'app? | Le entità e gli attributi |
| 7 · Le azioni | Per ogni funzione: cosa legge, cosa scrive? | Un pezzo alla volta |
| 8 · Chi può fare cosa | Chi vede? Chi modifica? | Un pezzo alla volta |
Il canvas sta nella cartella del progetto, in un file di testo: CANVAS.md. Lo scrivi a parole, non serve niente di speciale.
L'esempio che ti accompagna in tutto il libro si chiama Ritrovato: l'app degli oggetti smarriti di Nives. Il suo canvas lo costruiamo qui, un riquadro per volta.
1 · La frase
La prima domanda ha la forma di un modulo da riempire:
___ aiuta ___ a ___La frase di Ritrovato:
Ritrovato aiuta chi perde qualcosa sulla Linea Menta a ritrovarlo senza fare la coda allo sportello.Tre pezzi: il nome dell'app, chi aiuti, e cosa gli permetti di fare. Non c'è scritto «con quale tecnologia»: FastAPI e PostgreSQL non interessano a nessuno, tranne a te.
La prova: leggila a qualcuno che non programma. Se capisce, va bene. Se ti chiede «ma cos'è, esattamente?», riscrivila.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Prima di aprire, prova tu: riscrivi nella forma «___ aiuta ___ a ___» questa descrizione: «Ritrovato è un sistema di gestione degli oggetti smarriti con database e API».
- «Ritrovato aiuta chi perde qualcosa a ritrovarlo.» Il «gestione», il «database» e le «API» sono scomparsi: parlavano della costruzione, non di chi usa l'app.
- Se ti è venuta un'altra frase, controlla solo che i tre pezzi ci siano: chi, e cosa riesce a fare grazie all'app.
2 · Per chi
Chi la usa? Uno o due tipi di persone.
Non «tutti». Un'app per tutti non ha nessuno in mente, quindi non ha nessuna scelta da fare: ogni funzione sembra utile. Quando scegli per chi è, le scelte si fanno da sole.
Ritrovato ha due tipi di persone, e sono molto diverse:
Chi ha perso qualcosa (il passeggero: non ha un account).
Chi lavora all'ufficio oggetti smarriti di Porta Codice (l'addetto: Nives e i colleghi).Il passeggero apre l'app una volta, cerca, e se ne va. L'addetto la apre ogni giorno e registra. Già qui si vede una cosa che ti servirà: il passeggero non ha un account. Lo scrivi subito, perché ti torna utile due capitoli dopo.
3 · Il problema
Cosa fanno oggi, senza la tua app? Cosa non funziona?
Gli oggetti trovati finiscono in scatoloni con un cartellino scritto a mano.
Chi ha perso qualcosa telefona dalle 9 alle 12, e Nives cerca a memoria.
Dopo sessanta giorni gli oggetti non ritirati vanno in beneficenza, e nessuno lo sa.È il riquadro più facile da riempire male. Si scrive «manca un'app per gli oggetti smarriti»: ma questo non è un problema, è la tua soluzione travestita. Un problema è qualcosa che una persona vera vive, in un giorno vero, e che puoi raccontare senza nominare la tua app.
Se nessuno lo vive, non c'è progetto. Una prova che non sbaglia: puoi dare il nome di una persona che ha quel problema? Nives ha le telefonate. Se il nome non ti viene, parla con qualcuno prima di andare avanti.
4 · Le funzioni
Le cose che l'app sa fare. Tre regole:
- Tre indispensabili. Senza una di queste l'app non serve.
- Due «se avanza tempo». Si fanno dopo, se resta tempo.
- Cosa NON fa. Una lista, scritta.
Una funzione è una frase con un verbo: chi fa cosa. «Registro un oggetto» è una funzione. «Gestione oggetti» no: non dice chi, non dice cosa, e non sai dove finisce. Quelle frasi diventano subito altro: nel riquadro 7 un'azione (cosa leggo, cosa scrivo), nel capitolo Un pezzo alla volta una rotta.
| Così no | Così sì |
|---|---|
| gestione oggetti | registro un oggetto trovato (l'addetto) |
| ricerca | cerco tra gli oggetti trovati, per stazione, categoria e giorno (il passeggero) |
| restituzioni | restituisco un oggetto: a chi, quando (l'addetto) |
Le funzioni di Ritrovato:
Indispensabili:
1. registro un oggetto trovato (l'addetto)
2. cerco tra gli oggetti trovati, per stazione, categoria e giorno (il passeggero)
3. restituisco un oggetto: a chi, quando (l'addetto)
Se avanza tempo:
4. lascio una segnalazione «ho perso…» e ricevo un'email se arriva qualcosa di simile
5. la foto dell'oggetto
Cosa NON fa:
non spedisce niente a casa · niente pagamenti ·
documenti e portafogli non si mostrano online (vanno in Questura, come oggi)Perché il «NON» è il riquadro più utile
Le funzioni dicono cosa farai. Il «NON» dice cosa non farai, e ti protegge da te stesso. Quando a metà progetto ti viene un'idea bellissima («e se spedissimo gli oggetti a casa?»), non devi decidere da capo: guardi la lista. Se c'è scritto, la risposta è già lì. Se non c'è, scrivila adesso.
Il «NON» è il riquadro che risparmia più giorni. Ogni riga è un'intera parte di app che non devi costruire: i pagamenti, la spedizione, i documenti. E qualche volta è una questione di responsabilità, non di tempo: i documenti non si mostrano online perché non è giusto, non perché sia difficile.
5 · Le schermate
Quali pagine vede chi la usa? Da 3 a 5. Di meno, e l'app non fa quello che promette. Di più, e stai costruendo troppo.
La regola: ogni funzione ha almeno una schermata. Una funzione senza schermata è una funzione che nessuno può usare.
| Funzione | La schermata |
|---|---|
| 1 · registro un oggetto | nuovo oggetto |
| 2 · cerco | gli oggetti trovati (l'elenco, con i filtri), la scheda di un oggetto |
| 3 · restituisco | restituzione |
In più c'è il login dell'addetto, perché registrare e restituire sono solo per lui. Sono cinque schermate in tutto:
gli oggetti trovati (l'elenco, con i filtri) · la scheda di un oggetto (con «come ritirarlo») ·
nuovo oggetto (addetto) · restituzione (addetto) · login dell'addettoLe schermate si disegnano a mano, su un foglio, con un rettangolo per ogni pagina: non servono programmi. Basta vedere cosa c'è dentro. Per esempio, la prima:
┌────────────────────────────────────────────────┐
│ Gli oggetti trovati │
│ Stazione: [ tutte ] Categoria: [ tutte ] │
│ Giorno: [ __/__/____ ] [ Cerca ] │
├────────────────────────────────────────────────┤
│ ombrello blu Porta Codice 12 marzo │
│ borsa di tela Largo Lista 12 marzo │
│ chiavi con anello Piazza Query 11 marzo │
└────────────────────────────────────────────────┘Il disegno ti dice una cosa che il canvas a parole non dice: quali dati servono. In questo foglio ci sono un nome dell'oggetto, una stazione, un giorno, una categoria. Quelle sono le «cose» del riquadro 6: il capitolo Le entità parte da qui.
Le dieci domande per rileggere
Quando hai finito i riquadri, passa il canvas a un compagno e prendi il suo. Poi spiegatevi le app a vicenda, in un minuto. Se il compagno non riesce a spiegare la tua app, il canvas non è chiaro. Dieci domande, tutte con una risposta sì o no:
- La frase si capisce da chi non programma?
- Si sa per chi è: non «per tutti»?
- Il problema è vero: qualcuno lo vive davvero?
- Le funzioni indispensabili sono al massimo tre?
- C'è scritto cosa l'app NON fa?
- Ogni funzione ha almeno una schermata?
- Ogni schermata usa dati del riquadro 6?
- Le «cose» del riquadro 6 sono da 3 a 6?
- Per ogni funzione: cosa legge, cosa scrive?
- Si sa chi può modificare cosa?
Le prime sei le puoi fare adesso. La 7 e la 8 dopo il riquadro 6, la 9 e la 10 dopo i riquadri 7 e 8. Ma sappi già che esistono.
Dopo i cinque riquadri
Quello che hai scritto ha già una forma. Dalle funzioni nasceranno le azioni (riquadro 7) e le rotte della tua API. Dalle schermate nasceranno i dati del riquadro 6, e da quelli le tabelle. Il percorso, in ordine:
il canvas ──▶ le tabelle ──▶ le API ──▶ il login ──▶ online ──▶ l'interfaccia
(questo) (schema.sql) (FastAPI) (chi può)Ora tocca a te: nella palestra scrivi il «revisore», un programma che rilegge un canvas e dice quali domande non passano. E poi compili il CANVAS.md del tuo progetto.
Ricorda
- Cambiare un'idea sul foglio costa un minuto, cambiare un database giorni: le domande vengono prima.
- Il canvas ha otto riquadri; questo capitolo fa i primi cinque: la frase, per chi, il problema, le funzioni, le schermate.
- La frase è «___ aiuta ___ a ___»: la capisce anche chi non programma.
- Per chi: uno o due tipi di persone, mai «tutti». Il problema lo vive una persona vera.
- Una funzione è una frase con un verbo: chi fa cosa. Tre indispensabili, due «se avanza tempo», e la lista del «NON».
- Le schermate sono da 3 a 5, e ogni funzione ne ha almeno una. Il login non è una funzione.
- Le dieci domande si fanno a un compagno: se non sa spiegare la tua app in un minuto, riscrivi.