Rifattorizzare senza rompere
Cambiare la forma di un programma, non quello che fa
- 10 minuti di lettura
Negli uffici della Linea Menta ci sono programmi vecchi che funzionano, e che nessuno osa toccare. Hanno nomi di una lettera, righe lunghe un chilometro e un commento in cima: «non toccare». Eppure prima o poi qualcuno dovrà cambiarli.
Il problema non è scrivere il codice nuovo. Il problema è non rompere quello che c'è già.
Rifattorizzare vuol dire cambiare la forma di un programma senza cambiare il suo comportamento. Le sette regole ti dicono come dovrebbe essere scritto il codice. Questo capitolo ti dice come ci arrivi, partendo da un programma che esiste già, senza che ti scappi una virgola.
La difficoltà è questa: quando riscrivi, non vedi se hai rotto qualcosa. Il programma gira, stampa dei numeri, e i numeri sembrano giusti. Ti serve qualcuno che lo controlli al posto tuo.
Il disegno
Il trucco è fare una fotografia dell'uscita del programma, prima di toccarlo. Poi, dopo ogni modifica, rifai la fotografia e le confronti.
PRIMA DI TOCCARE DOPO OGNI MODIFICA
programma programma (modificato)
│ lancio con un file di dati │ stesso file di dati
▼ ▼
uscita ──▶ ATTESO (la fotografia) uscita ──▶ confronto con ATTESO
│
uguale ───────┴─────── diversa
│ │
VERDE ROSSO
un commit, si va avanti torni indietroQuesta fotografia ha un nome inglese: golden master. La uscita «d'oro» di riferimento. Se il programma stampa ancora la stessa cosa, hai cambiato la forma e non il comportamento.
Il golden master, visto da chi lo usa
Un test golden master fa tre cose.
- Lancia il programma come lo lanceresti tu dal terminale, con un file di dati.
- Prende quello che ha stampato.
- Lo confronta con la fotografia, che è scritta dentro il test.
Nel tuo zip c'è già tutto: la funzione lancia lancia il programma e ti restituisce tre cose.
from pathlib import Path
from controlli.lancia_programma import lancia
uscita = lancia(Path("guasti_tornelli.py"), "guasti.csv")
print(repr(uscita.out)) # tutto quello che è andato su stdout
print(repr(uscita.err)) # tutto quello che è andato su stderr
print(uscita.codice) # 0 se il programma è finito bene'Porta Codice: 7 ore ferme (grave)\nVia Variabile: 4 ore ferme\nLargo Lista: 3 ore ferme\nPonte Ciclo: 6 ore ferme (grave)\n'
'Riga 5 ignorata: T-04,Largo Lista,x\n'
0repr mostra anche gli a capo (\n) e gli spazi. È quello che il test vede: ogni carattere.
Il test è corto:
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)Quello dopo la virgola dell'assert è il messaggio che compare se il test è rosso: differenza ti dice dove le due uscite smettono di essere uguali, in italiano.
L'ATTESO si ottiene lanciando il programma com'è e copiando quello che stampa. Non lo scrivi tu a mente: se lo scrivessi a mente, ci metteresti dentro quello che pensi che faccia, non quello che fa.
Non cambia di un carattere
«Uguale» qui vuol dire uguale fino all'ultimo spazio. Una cosa che a te sembra la stessa, per il test è un'altra.
| Prima | Dopo | Perché è rosso |
|---|---|---|
Ponte Ciclo: 6 ore ferme | Ponte Ciclo: 6.0 ore ferme | Hai messo un float al posto di un int |
incasso 175.60 | incasso 175.6 | round(x, 2) non è :.2f: il secondo scrive sempre due decimali |
1 uscite | 1 uscita | Sembra un errore di italiano, ma è quello che il programma faceva. Lo cambierai con un altro test |
Porta Codice poi Largo Lista | Largo Lista poi Porta Codice | L'ordine delle righe è parte dell'uscita |
| l'ultima riga finisce con un a capo | l'ultima riga non ha l'a capo | Un end="" di troppo |
print(9.0)
print(f"{9.0:.2f}")9.0
9.00Stesso numero, due modi di scriverlo. Per un test sono due uscite diverse.
Gli avvisi vanno su stderr
Nel libro Python hai visto che un programma ha due canali di uscita: stdout per i risultati, stderr per gli avvisi (Moduli e file).
Succede spesso, nei programmi vecchi: una riga del file dei dati è storta, il programma la salta con un except: e un pass, e nessuno lo sa mai. Rifattorizzando vuoi che quell'errore si veda, ma senza toccare lo stdout (la fotografia). La strada è stderr.
try:
ore = int(riga_divisa[2])
except ValueError:
print(f"Riga {numero} ignorata: {riga.strip()}", file=sys.stderr)Due cose in una: l'except prende solo l'errore che ti aspetti (ValueError, quello di int("x")), e l'avviso va su stderr. Lo stdout non cambia di un carattere.
Per il terminale i due canali sono separati. Con > mandi lo stdout in un file, e gli avvisi restano sullo schermo:
python guasti_tornelli.py guasti.csv > resoconto.txtRiga 5 ignorata: T-04,Largo Lista,xIl test dell'avviso guarda uscita.err, e il formato esatto lo decide la consegna. Come funzionano try, except e raise lo trovi in try, except, raise.
Se trovi un bug
Mentre riscrivi un programma vecchio, leggi ogni riga. E prima o poi ne trovi una che non torna: un > che doveva essere >=, un turno di notte che dà ore negative.
Sarebbe bello correggerla subito. Non farlo. Il golden master ha la fotografia del programma con quel bug dentro: correggerlo cambia l'uscita, e il test diventa rosso. Peggio: se lo correggi senza dirlo, nessuno sa che l'uscita di ieri sera era sbagliata.
Si fa così:
- Lo segnali nel codice, con un commento che comincia per
# BUG:, accanto alla riga. - Lo scrivi nella pull request (GitHub e le pull request), così chi decide sa che c'è.
- Lo correggi dopo, in una modifica a parte, con un test nuovo che descrive il comportamento giusto.
def 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:I bug che non fanno rumore, quelli che danno un numero sbagliato senza nessun traceback, hanno un capitolo loro: I bug silenziosi.
Passi piccoli
Rifattorizzare non si fa tutto insieme. Si fa un passo piccolo alla volta, e ogni passo ha lo stesso giro.
un cambiamento piccolo ──▶ pytest ──┬── verde ──▶ git commit ──▶ il passo dopo
│
└── rosso ──▶ git diff (cosa ho cambiato?)
git restore (torno all'ultimo verde)| Il passo | Come lo fai |
|---|---|
| Dare un nome nuovo a una variabile | In VS Code: clic sul nome, tasto F2 (Rename Symbol), scrivi il nome nuovo, Invio. Cambia tutte le occorrenze, e solo quelle |
| Mettere un pezzo in una funzione | A mano, un pezzo alla volta: scrivi la def, sposta le righe, chiamala. Poi pytest |
| Un numero diventa una costante | Una riga in cima al file, poi la sostituzione, poi pytest |
| Qualcosa diventa rosso | git diff per vedere cosa hai cambiato. Se non lo capisci, git restore e rifai il passo più piccolo |
Perché piccoli? Perché quando un test diventa rosso, il colpevole è l'ultima cosa che hai fatto. Se hai fatto dieci cose, il colpevole è uno di dieci. Se hai fatto una cosa, è quella.
Git, per questo, è lo strumento giusto: ogni commit è un punto in cui sai che tutto funzionava. I comandi sono quelli di Il giro di ogni giorno e di Rimettere a posto.
Il collegamento con quello che viene dopo
Il golden master è un test scritto sull'uscita: non sa dove si rompe, sa solo che qualcosa è cambiato. Per controllare una funzione alla volta, con un nome per ogni caso, servono test veri: li scrivi in Scrivere un test. E in Prima il test il test viene perfino prima del codice.
Ricorda
- Rifattorizzare è cambiare la forma, non il comportamento.
- Prima di toccare un programma, si fotografa l'uscita: golden master.
- Lo stdout non cambia di un carattere:
9.0non è9.00,1 usciteresta1 uscite. - Gli avvisi vanno su stderr, e l'
exceptprende solo l'errore che ti aspetti. - Un bug trovato strada facendo si segnala con
# BUG:, non si corregge. - Un passo piccolo, pytest, commit. Rosso?
git diff, poigit restore.