Vai al contenuto
code-to-code

Apro l'indice…

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

Codice pulito e test2. Rifattorizzare senza romperep. 35

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 indietro

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

  1. Lancia il programma come lo lanceresti tu dal terminale, con un file di dati.
  2. Prende quello che ha stampato.
  3. 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.

Python
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'
0

repr mostra anche gli a capo (\n) e gli spazi. È quello che il test vede: ogni carattere.

Il test è corto:

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

PrimaDopoPerché è rosso
Ponte Ciclo: 6 ore fermePonte Ciclo: 6.0 ore fermeHai messo un float al posto di un int
incasso 175.60incasso 175.6round(x, 2) non è :.2f: il secondo scrive sempre due decimali
1 uscite1 uscitaSembra un errore di italiano, ma è quello che il programma faceva. Lo cambierai con un altro test
Porta Codice poi Largo ListaLargo Lista poi Porta CodiceL'ordine delle righe è parte dell'uscita
l'ultima riga finisce con un a capol'ultima riga non ha l'a capoUn end="" di troppo
Python
print(9.0)
print(f"{9.0:.2f}")
9.0
9.00

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

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

Terminale
python guasti_tornelli.py guasti.csv > resoconto.txt
Riga 5 ignorata: T-04,Largo Lista,x

Il 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ì:

  1. Lo segnali nel codice, con un commento che comincia per # BUG:, accanto alla riga.
  2. Lo scrivi nella pull request (GitHub e le pull request), così chi decide sa che c'è.
  3. Lo correggi dopo, in una modifica a parte, con un test nuovo che descrive il comportamento giusto.
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:

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 passoCome lo fai
Dare un nome nuovo a una variabileIn 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 funzioneA mano, un pezzo alla volta: scrivi la def, sposta le righe, chiamala. Poi pytest
Un numero diventa una costanteUna riga in cima al file, poi la sostituzione, poi pytest
Qualcosa diventa rossogit 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.0 non è 9.00, 1 uscite resta 1 uscite.
  • Gli avvisi vanno su stderr, e l'except prende 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, poi git restore.