Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

Il progetto1. Le domande da farsip. 1

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'erroreCosa devi rifare
Sul foglioUna riga cancellata. Un minuto
Nelle tabelleLo schema, i dati di prova, le query
Nelle rotteTutto quello che sta sopra le tabelle, e i test
Nell'interfacciaLe 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     │
└───────────────────┴───────────────────┴───────────────────┘
RiquadroLa domandaDove
1 · La fraseCosa fa la tua app, in una frase?Questo capitolo
2 · Per chiChi la usa?Questo capitolo
3 · Il problemaCosa fanno oggi, senza la tua app?Questo capitolo
4 · Le funzioniLe 3 cose che deve saper fareQuesto capitolo
5 · Le schermateQuali pagine vede chi la usa?Questo capitolo
6 · I datiQuali «cose» ricorda l'app?Le entità e gli attributi
7 · Le azioniPer ogni funzione: cosa legge, cosa scrive?Un pezzo alla volta
8 · Chi può fare cosaChi 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:

  1. Tre indispensabili. Senza una di queste l'app non serve.
  2. Due «se avanza tempo». Si fanno dopo, se resta tempo.
  3. 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ì noCosì sì
gestione oggettiregistro un oggetto trovato (l'addetto)
ricercacerco tra gli oggetti trovati, per stazione, categoria e giorno (il passeggero)
restituzionirestituisco 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.

FunzioneLa schermata
1 · registro un oggettonuovo oggetto
2 · cercogli oggetti trovati (l'elenco, con i filtri), la scheda di un oggetto
3 · restituiscorestituzione

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'addetto

Le 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:

  1. La frase si capisce da chi non programma?
  2. Si sa per chi è: non «per tutti»?
  3. Il problema è vero: qualcuno lo vive davvero?
  4. Le funzioni indispensabili sono al massimo tre?
  5. C'è scritto cosa l'app NON fa?
  6. Ogni funzione ha almeno una schermata?
  7. Ogni schermata usa dati del riquadro 6?
  8. Le «cose» del riquadro 6 sono da 3 a 6?
  9. Per ogni funzione: cosa legge, cosa scrive?
  10. 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.