Rifattorizzare, esercizi spiegati
Un programma vecchio, quattro modi di non rompere niente
- 25 minuti di lettura
Quattro esempi, sullo stesso programma: un vecchio conto delle ore di fermo dei tornelli. Ognuno ha lo stesso ritmo:
- Prevedi: leggi e scrivi su un foglio cosa succede. Prima di aprire la risposta.
- In italiano: cosa fa il programma, a parole.
- Passo per passo: cosa cambia a ogni giro, o a ogni commit.
- Cosa portiamo a casa: la cosa da ricordare.
Gli output di questa pagina sono veri: li abbiamo ottenuti lanciando davvero i comandi, in una cartella con un repository Git di prova. Puoi rifare tutto a mano: una cartella nuova, i file qui sotto, git init.
A · La fotografia
Un tornello che si ferma costa ore di lavoro. Aldo Ronchi, il programmatore della biglietteria, ha lasciato questo programmino: somma le ore di fermo per stazione. Il file dei guasti:
tornello,stazione,ore_fermo
T-01,Porta Codice,2
T-02,Porta Codice,5
T-03,Via Variabile,4
T-04,Largo Lista,x
T-05,Largo Lista,3
T-06,Ponte Ciclo,6E il programma, guasti_tornelli.py:
"""Guasti dei tornelli: ore di fermo per stazione.
Una stazione con 4 ore di fermo o più è «grave»."""
import sys
f = open(sys.argv[1])
l = f.readlines()
f.close()
d = {}
for r in l[1:]:
try:
p = r.strip().split(",")
d[p[1]] = d.get(p[1], 0) + int(p[2])
except:
pass
for s in d:
if d[s] > 4:
print(s + ": " + str(d[s]) + " ore ferme (grave)")
else:
print(s + ": " + str(d[s]) + " ore ferme")Prima di toccare una riga, cosa stampa python guasti_tornelli.py guasti.csv? Scrivi le quattro righe. Attenzione a Via Variabile e a Largo Lista.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Porta Codice: 7 ore ferme (grave)
Via Variabile: 4 ore ferme
Largo Lista: 3 ore ferme
Ponte Ciclo: 6 ore ferme (grave)- Porta Codice: 2 + 5 = 7, e 7 è più di 4: grave.
- Via Variabile: 4 ore. Il programma chiede
d[s] > 4, e 4 non è più di 4: non è grave. Eppure la docstring dice «4 ore o più». Tieni a mente questa riga: ci torniamo nell'esempio D. - Largo Lista: la riga T-04 ha
xal posto delle ore,int("x")dà un errore, l'exceptlo fa sparire. Restano le 3 ore di T-05. - Ponte Ciclo: 6, grave.
In italiano.
- Apro il file e leggo tutte le righe.
- Salto la prima (l'intestazione).
- Per ogni riga: la spezzo alle virgole, e aggiungo le ore alla stazione. Se qualcosa va storto, la salto.
- Per ogni stazione stampo il totale, con «(grave)» se supera 4.
Il disegno.
Passo per passo.
| Riga del file | p (la riga spezzata) | Cosa succede | d dopo |
|---|---|---|---|
| T-01 | ["T-01", "Porta Codice", "2"] | 0 + 2 | {"Porta Codice": 2} |
| T-02 | ["T-02", "Porta Codice", "5"] | 2 + 5 | {"Porta Codice": 7} |
| T-03 | ["T-03", "Via Variabile", "4"] | 0 + 4 | più "Via Variabile": 4 |
| T-04 | ["T-04", "Largo Lista", "x"] | int("x") fallisce: l'except salta la riga | non cambia |
| T-05 | ["T-05", "Largo Lista", "3"] | 0 + 3 | più "Largo Lista": 3 |
| T-06 | ["T-06", "Ponte Ciclo", "6"] | 0 + 6 | più "Ponte Ciclo": 6 |
Adesso la fotografia. Un test che lancia il programma e confronta lo stdout con quello che hai appena visto, copiato com'è:
from pathlib import Path
from controlli.lancia_programma import differenza, lancia
QUI = Path(__file__).parent
PROGRAMMA = QUI / "guasti_tornelli.py"
ATTESO = (
"Porta Codice: 7 ore ferme (grave)\n"
"Via Variabile: 4 ore ferme\n"
"Largo Lista: 3 ore ferme\n"
"Ponte Ciclo: 6 ore ferme (grave)\n"
)
def test_stesso_resoconto():
uscita = lancia(PROGRAMMA, "guasti.csv")
assert uscita.out == ATTESO, differenza(ATTESO, uscita.out)pytest -vtest_guasti_tornelli.py::test_stesso_resoconto PASSED [100%]Verde sul programma di Aldo: la fotografia è giusta. Per vedere che il test serve davvero, proviamo a rovinare il programma di un niente: «ore ferme» diventa «ore di fermo».
def test_stesso_resoconto():
uscita = lancia(PROGRAMMA, "guasti.csv")
> assert uscita.out == ATTESO, differenza(ATTESO, uscita.out)
E AssertionError: L'uscita è cambiata alla riga 1.
E prima: 'Porta Codice: 7 ore ferme (grave)'
E adesso: 'Porta Codice: 7 ore di fermo (grave)'Si legge così: la riga prima: è la fotografia, la riga adesso: è quello che il programma stampa ora. Il test non sa cosa hai cambiato, ma ti dice dove guardare: la riga 1 dell'uscita.
Cosa portiamo a casa. La fotografia si fa prima di toccare il programma, lanciandolo com'è, e si copia quello che stampa. Da lì in poi, ogni modifica ha un giudice.
B · Un passo alla volta
Adesso il programma si rimette a posto. Il repository è già pronto, con il primo commit: il programma di Aldo, il suo golden master, controlli/. Da qui, un commit per ogni passo.
Il primo passo è il più sicuro: i nomi. Solo i nomi, nient'altro. In VS Code: clic su d, F2, ore_per_stazione, Invio, e così per le altre.
file = open(sys.argv[1])
righe = file.readlines()
file.close()
ore_per_stazione = {}
for riga in righe[1:]:
try:
pezzi = riga.strip().split(",")
ore_per_stazione[pezzi[1]] = ore_per_stazione.get(pezzi[1], 0) + int(pezzi[2])
except:
pass
for stazione in ore_per_stazione:
if ore_per_stazione[stazione] > 4:
print(stazione + ": " + str(ore_per_stazione[stazione]) + " ore ferme (grave)")
else:
print(stazione + ": " + str(ore_per_stazione[stazione]) + " ore ferme")Il secondo passo: la frase che il programma stampa compare due volte, quasi uguale. Mettiamola in una funzione. Prima di guardare cosa succede, prevedi: se mentre ricopio la frase scrivo «fermi» invece di «ferme» in una riga sola, quando te ne accorgi?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Subito, al primo pytest: il golden master controlla ogni carattere, anche un refuso che nessun occhio avrebbe notato. Ecco la sessione, uscite vere comprese.
$ pytest -q
. [100%]
1 passed in 0.02s
$ git commit -am "Dai un nome alle variabili"
d6ffa91 Dai un nome alle variabiliFin qui il passo dei nomi: verde, commit. Poi la funzione, con il refuso:
$ pytest -q
F [100%]
=================================== FAILURES ===================================
____________________________ test_stesso_resoconto _____________________________
def test_stesso_resoconto():
uscita = lancia(PROGRAMMA, "guasti.csv")
> assert uscita.out == ATTESO, differenza(ATTESO, uscita.out)
E AssertionError: L'uscita è cambiata alla riga 1.
E prima: 'Porta Codice: 7 ore ferme (grave)'
E adesso: 'Porta Codice: 7 ore fermi (grave)'Il test dice «riga 1 dell'uscita», ma non dice dove, nel codice, hai sbagliato. Questo lo dice Git:
$ git diff
diff --git a/guasti_tornelli.py b/guasti_tornelli.py
index 2d8212c..87df8af 100644
--- a/guasti_tornelli.py
+++ b/guasti_tornelli.py
@@ -3,6 +3,13 @@ Una stazione con 4 ore di fermo o più è «grave»."""
import sys
+
+def descrivi(stazione, ore):
+ if ore > 4:
+ return stazione + ": " + str(ore) + " ore fermi (grave)"
+ return stazione + ": " + str(ore) + " ore ferme"
+
+
file = open(sys.argv[1])
righe = file.readlines()
file.close()
@@ -14,7 +21,4 @@ for riga in righe[1:]:
except:
pass
for stazione in ore_per_stazione:
- if ore_per_stazione[stazione] > 4:
- print(stazione + ": " + str(ore_per_stazione[stazione]) + " ore ferme (grave)")
- else:
- print(stazione + ": " + str(ore_per_stazione[stazione]) + " ore ferme")
+ print(descrivi(stazione, ore_per_stazione[stazione]))Il + con scritto «fermi» è lì. Potresti correggerlo a mano. Ma hai fatto un passo solo, ed è piccolo: più veloce e più sicuro tornare all'ultimo verde e rifarlo.
$ git restore guasti_tornelli.py
$ pytest -q
. [100%]
1 passed in 0.02sRifatto il passo, stavolta copiando con più attenzione:
$ pytest -q
. [100%]
1 passed in 0.02s
$ git commit -am "Metti la frase del resoconto in una funzione"
$ git log --oneline
16c4588 Metti la frase del resoconto in una funzione
d6ffa91 Dai un nome alle variabili
ecf6416 Aggiungi il programma di Aldo e il suo golden masterIn italiano. Ogni commit è un punto sicuro: il programma funzionava, il test lo dice. Se un passo va male, torni all'ultimo punto sicuro senza perdere niente.
Il disegno.
Passo per passo.
| Passo | Cosa cambi | pytest | Poi |
|---|---|---|---|
| 1 | I nomi (con F2) | verde | commit «Dai un nome alle variabili» |
| 2 | La frase in una funzione, con un refuso | rosso | git diff, git restore |
| 2 bis | La stessa funzione, copiata meglio | verde | commit «Metti la frase del resoconto in una funzione» |
Cosa portiamo a casa. Un cambiamento, pytest, commit. Se è rosso, la colpa è dell'ultimo cambiamento: guarda git diff e, se non la vedi subito, git restore e rifai il passo più piccolo. Più piccolo è il passo, meno costa tornare indietro. Se i comandi di Git ti sembrano un ripasso lontano: Il giro di ogni giorno e Rimettere a posto.
C · La riga storta, su stderr
Il programma, adesso, ha nomi e una funzione. Ma resta quell'except: con il pass: la riga T-04 sparisce e nessuno lo sa. Vogliamo che il programma lo dica, senza toccare lo stdout.
Prima di scrivere il codice, scrivi il test. Quale riga dovrebbe dire il programma? Il file ha l'intestazione alla riga 1, quindi T-04 è alla riga 5.
def test_riga_rotta_su_stderr():
uscita = lancia(PROGRAMMA, "guasti.csv")
atteso = "Riga 5 ignorata: T-04,Largo Lista,x\n"
assert uscita.err == atteso, differenza(atteso, uscita.err)Rosso, com'è giusto: il programma non dice niente su stderr.
$ pytest -q
.F [100%]
=================================== FAILURES ===================================
__________________________ test_riga_rotta_su_stderr ___________________________
def test_riga_rotta_su_stderr():
uscita = lancia(PROGRAMMA, "guasti.csv")
atteso = "Riga 5 ignorata: T-04,Largo Lista,x\n"
> assert uscita.err == atteso, differenza(atteso, uscita.err)
E AssertionError: L'uscita è più corta: manca la riga 1, 'Riga 5 ignorata: T-04,Largo Lista,x'Adesso il codice. Due modifiche nello stesso punto: l'except prende solo ValueError (l'errore di int("x")), e l'avviso va su stderr. Per sapere a che riga siamo c'è enumerate, che parte da 2 perché la riga 1 è l'intestazione.
for numero, riga in enumerate(righe[1:], start=2):
try:
pezzi = riga.strip().split(",")
ore_per_stazione[pezzi[1]] = ore_per_stazione.get(pezzi[1], 0) + int(pezzi[2])
except ValueError:
print(f"Riga {numero} ignorata: {riga.strip()}", file=sys.stderr)$ pytest -q
.. [100%]
2 passed in 0.04sTutti e due verdi: il golden master (stdout) non è cambiato, il test nuovo (stderr) funziona. Guardiamo cosa vede chi lancia il programma, e come si separano i due canali:
$ python guasti_tornelli.py guasti.csv
Riga 5 ignorata: T-04,Largo Lista,x
Porta Codice: 7 ore ferme (grave)
Via Variabile: 4 ore ferme
Largo Lista: 3 ore ferme
Ponte Ciclo: 6 ore ferme (grave)
$ python guasti_tornelli.py guasti.csv > resoconto.txt
Riga 5 ignorata: T-04,Largo Lista,x
$ cat resoconto.txt
Porta Codice: 7 ore ferme (grave)
Via Variabile: 4 ore ferme
Largo Lista: 3 ore ferme
Ponte Ciclo: 6 ore ferme (grave)
$ python guasti_tornelli.py guasti.csv 2> avvisi.txt
Porta Codice: 7 ore ferme (grave)
Via Variabile: 4 ore ferme
Largo Lista: 3 ore ferme
Ponte Ciclo: 6 ore ferme (grave)
$ cat avvisi.txt
Riga 5 ignorata: T-04,Largo Lista,x> manda in un file lo stdout (e l'avviso resta sullo schermo), 2> manda in un file lo stderr. Sono due canali diversi: per questo la fotografia dello stdout non è cambiata.
In italiano. La riga storta non sparisce più in silenzio: il programma la nomina su stderr, e il resoconto resta quello di prima.
Passo per passo.
| Cosa | Prima | Dopo |
|---|---|---|
L'except | except: prende tutto, anche un bug | except ValueError: prende solo il numero che non è un numero |
Cosa fa nell'except | pass | un avviso su stderr, con il numero di riga |
| Lo stdout | quattro righe | le stesse quattro righe |
| Lo stderr | vuoto | Riga 5 ignorata: T-04,Largo Lista,x |
Cosa portiamo a casa. Un except si scrive stretto (ValueError, non Exception, non da solo) e non tace: quello che scarta lo dice, su stderr. Perché stderr? Perché lo stdout è la fotografia, e non si tocca.
D · Il bug che si segnala
Torniamo alla riga di Via Variabile. La docstring dice che una stazione con 4 ore o più è grave. Il codice dice > 4. Via Variabile ha esattamente 4 ore, e il resoconto di ogni sera dice «non grave».
È un bug. Il confine è sbagliato. E la tentazione è forte: basta un = in più.
Prima di provare, prevedi: se cambi ore > 4 in ore >= 4, cosa dice pytest?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Rosso: la fotografia ha Via Variabile senza «(grave)», e il programma corretto la scrive con.
$ pytest -q
F. [100%]
=================================== FAILURES ===================================
____________________________ test_stesso_resoconto _____________________________
def test_stesso_resoconto():
uscita = lancia(PROGRAMMA, "guasti.csv")
> assert uscita.out == ATTESO, differenza(ATTESO, uscita.out)
E AssertionError: L'uscita è cambiata alla riga 2.
E prima: 'Via Variabile: 4 ore ferme'
E adesso: 'Via Variabile: 4 ore ferme (grave)'Il test ha fatto il suo lavoro: ti ha detto che il comportamento è cambiato. Che sia una correzione giusta non è affar suo.
Perché non correggere? Per tre ragioni.
- La sede ha già archiviato i resoconti di ogni sera: se da domani Via Variabile compare «grave» senza spiegazione, qualcuno chiama.
- Non sai ancora quante altre cose dipendono da quel confine.
- Se mescoli una rifattorizzazione con una correzione, quando un test diventa rosso non sai più quale delle due cose l'ha rotto.
Quindi: torni all'ultimo verde e segnali.
$ git restore guasti_tornelli.pydef descrivi(stazione, ore):
# BUG: la docstring dice «4 ore o più», ma con `>` quattro ore esatte non sono gravi.
# Non lo correggo: il resoconto di ogni sera cambierebbe. Lo segnalo nella pull request.
if ore > 4:
return stazione + ": " + str(ore) + " ore ferme (grave)"
return stazione + ": " + str(ore) + " ore ferme"$ pytest -q
.. [100%]
2 passed in 0.03s
$ git commit -am "Segnala il bug delle quattro ore"
$ git log --oneline
2003e1c Segnala il bug delle quattro ore
4eee63e Dì le righe scartate su stderr
16c4588 Metti la frase del resoconto in una funzione
d6ffa91 Dai un nome alle variabili
ecf6416 Aggiungi il programma di Aldo e il suo golden masterCinque commit, cinque passi piccoli, e il resoconto non è cambiato di un carattere. Nella descrizione della pull request, il bug ha il suo paragrafo:
Rifattorizzazione di guasti_tornelli.py: nomi, una funzione, avvisi su stderr.
Il resoconto su stdout è identico (golden master verde).
Bug trovato, NON corretto: una stazione con esattamente 4 ore di fermo non è
segnalata «grave», ma la docstring dice «4 ore o più». Vedi il commento # BUG:
in descrivi(). Da correggere in una modifica a parte, con un test nuovo.In italiano. Il bug resta, ma adesso si vede: c'è un commento accanto alla riga e una frase nella pull request. Chi decide può correggerlo con un test suo.
Passo per passo.
| Cosa fai | Perché |
|---|---|
Provi >= e lanci pytest | Vedi cosa dice il test |
| Rosso: il comportamento è cambiato | Il golden master protegge il resoconto |
git restore | Torni all'ultimo verde |
Scrivi # BUG: … accanto alla riga | Chi legge il codice lo sa |
| Lo scrivi nella pull request | Chi decide lo sa |
| Lo correggi dopo, con un test nuovo | Una modifica, una ragione |
Cosa portiamo a casa. Un golden master rosso dopo una «correzione» non è un fastidio: è la prova che stai cambiando il comportamento. Rifattorizzare e correggere sono due mestieri, uno per volta. Per le correzioni: un test che descrive il comportamento giusto, in Scrivere un test.