Vai al contenuto
code-to-code

Apro l'indice…

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

Codice pulito e test2. Rifattorizzare senza romperep. 40

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:

  1. Prevedi: leggi e scrivi su un foglio cosa succede. Prima di aprire la risposta.
  2. In italiano: cosa fa il programma, a parole.
  3. Passo per passo: cosa cambia a ogni giro, o a ogni commit.
  4. 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,6

E il programma, guasti_tornelli.py:

Python
"""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 x al posto delle ore, int("x") dà un errore, l'except lo fa sparire. Restano le 3 ore di T-05.
  • Ponte Ciclo: 6, grave.

In italiano.

  1. Apro il file e leggo tutte le righe.
  2. Salto la prima (l'intestazione).
  3. Per ogni riga: la spezzo alle virgole, e aggiungo le ore alla stazione. Se qualcosa va storto, la salto.
  4. Per ogni stazione stampo il totale, con «(grave)» se supera 4.

Il disegno.

inizio guasti_tornelli.py leggi le righe del file per ogni r in l[1:] se la riga dà errore sì: passo salta la riga no: d[stazione] = d[stazione] + ore per ogni s in d se d[s] > 4 sì: mostra s: ore ferme (grave) no: mostra s: ore fermeguasti_tornelli.pyleggi le righe del fileper ogni r in l[1:]la riga dà errored[stazione] = d[stazione] +oresalta la rigaper ogni s in dd[s] > 4mostra s: ore fermemostra s: ore ferme (grave)nosìfinitinosìfiniti
Il programma di Aldo

Passo per passo.

Riga del filep (la riga spezzata)Cosa succeded 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 + 4più "Via Variabile": 4
T-04["T-04", "Largo Lista", "x"]int("x") fallisce: l'except salta la riganon cambia
T-05["T-05", "Largo Lista", "3"]0 + 3più "Largo Lista": 3
T-06["T-06", "Ponte Ciclo", "6"]0 + 6più "Ponte Ciclo": 6
d = {"Porta Codice": 7, "Via Variabile": 4, "Largo Lista": 3, "Ponte Ciclo": 6}ddict"Porta Codice"7"Via Variabile"4"Largo Lista"3"Ponte Ciclo"6
Il dizionario d alla fine del ciclo

Adesso la fotografia. Un test che lancia il programma e confronta lo stdout con quello che hai appena visto, copiato com'è:

Python
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)
Terminale
pytest -v
test_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.

Python
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 variabili

Fin 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.02s

Rifatto 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 master

In 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.

inizio un cambiamento piccolo lancia pytest se pytest è verde sì: git commit no: git diff git restore rifai il passo più piccoloun cambiamento piccololancia pytestpytest è verdegit diffgit restorerifai il passo più piccologit commitnosì
Un passo alla volta

Passo per passo.

PassoCosa cambipytestPoi
1I nomi (con F2)verdecommit «Dai un nome alle variabili»
2La frase in una funzione, con un refusorossogit diff, git restore
2 bisLa stessa funzione, copiata meglioverdecommit «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.

Python
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.

Python
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.04s

Tutti 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.

CosaPrimaDopo
L'exceptexcept: prende tutto, anche un bugexcept ValueError: prende solo il numero che non è un numero
Cosa fa nell'exceptpassun avviso su stderr, con il numero di riga
Lo stdoutquattro righele stesse quattro righe
Lo stderrvuotoRiga 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.py
Python
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:
        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 master

Cinque 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 faiPerché
Provi >= e lanci pytestVedi cosa dice il test
Rosso: il comportamento è cambiatoIl golden master protegge il resoconto
git restoreTorni all'ultimo verde
Scrivi # BUG: … accanto alla rigaChi legge il codice lo sa
Lo scrivi nella pull requestChi decide lo sa
Lo correggi dopo, con un test nuovoUna 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.