Vai al contenuto
code-to-code

Apro l'indice…

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

Codice pulito e test1. Sette regole per chi leggep. 1

Sette regole per chi legge

Il codice si scrive per chi lo legge

  • 15 minuti di lettura

Di notte, al deposito della Linea Menta, il manutentore Ivo Brambati scrive gli script di cui ha bisogno. Di corsa, e solo per sé. La mattina dopo li deve leggere la capostazione di Piazza Query, Marta Villa. Ivo è già a casa a dormire.

Un programma lo leggi molte più volte di quante lo scrivi. Chi lo legge, quasi sempre, non sei tu mentre scrivi: sei tu fra tre mesi, o un collega che non ti può chiedere niente. Questo capitolo è il bigino di sette regole per scrivere per chi legge.

Un codice da indovinare

Ecco lo script di Ivo. Il registro dei tornelli dice quanti minuti ogni dipendente è rimasto in servizio. Leggilo senza fretta.

Python
def f(r):
    t = 0
    for x in r:
        try:
            a, b = x.split(",")
            m = int(b) - 480
            if m > 0:
                t = t + m * 0.4
        except:
            pass
    return t


registro = ["B-01,510", "B-03,470", "B-12,545", "B-07,boh"]
print(f(registro))
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.

Cosa stampa? E soprattutto: cosa fa, a parole? Prova a dirlo prima di guardare.

38.0

Lo script calcola quanto si paga di straordinari. Ogni riga è un badge e i minuti di servizio. Il turno dura 480 minuti (otto ore): quelli in più sono straordinario, pagato 0,4 euro al minuto. B-01 ha 30 minuti extra, B-12 ne ha 65, B-03 nessuno. Fanno 12 + 26 euro. La riga di B-07 (boh) è rotta, ma nessuno lo dice: sparisce.

Se l'hai indovinato bene, hai impiegato più di un minuto. Se non l'hai indovinato, è normale: il codice funziona, ma non si fa capire.

Cosa te l'ha reso difficile?

Rileggilo e chiediti: cosa ti ha fatto perdere tempo? Probabilmente cinque cose:

  • f, r, t, x, a, b, m: nomi che non dicono niente;
  • 480 e 0.4: da dove vengono?
  • una funzione sola che legge righe, converte, calcola e somma;
  • un except: pass che butta via la riga rotta senza dirlo a nessuno;
  • nessuna spiegazione, e un po' di spazi messi a caso.

Lo stesso programma, scritto per chi legge:

Python
import sys

MINUTI_DI_TURNO = 480
EURO_AL_MINUTO = 0.4


def minuti_extra(minuti_in_servizio: int) -> int:
    if minuti_in_servizio > MINUTI_DI_TURNO:
        return minuti_in_servizio - MINUTI_DI_TURNO
    return 0


def compenso_straordinari(righe: list[str]) -> float:
    compenso = 0.0
    for numero_riga, riga in enumerate(righe, start=1):
        try:
            badge, minuti = riga.split(",")
            compenso = compenso + minuti_extra(int(minuti)) * EURO_AL_MINUTO
        except ValueError:
            print(f"Riga {numero_riga} ignorata: {riga}", file=sys.stderr)
    return compenso


registro = ["B-01,510", "B-03,470", "B-12,545", "B-07,boh"]
print(compenso_straordinari(registro))

Lo lanciamo:

Riga 4 ignorata: B-07,boh
38.0

Fa la stessa cosa: 38.0 sullo schermo. Ma adesso Marta può leggerlo, e vede anche la riga rotta. Cambia come è scritto, non cosa fa: si chiama rifattorizzare ed è il tema del prossimo capitolo.

Il disegno

Ivo, di notte                           Marta, la mattina dopo

scrive  ──────▶  il file  ──────▶  lo legge: «cosa fa questo?»
                    │
                    └─ Ivo non c'è. Il file deve parlare da solo.

Le sette regole sono le sette domande che Marta si fa:

  1  nomi                     cosa c'è in questa variabile?
  2  una funzione, un compito cosa fa questa funzione, in una frase?
  3  niente numeri magici     da dove viene quel 480?
  4  errori non nascosti      se qualcosa va storto, lo vengo a sapere?
  5  non ripeterti            questo pezzo l'ho già letto?
  6  commenti sul perché      perché lo fa così?
  7  forma                    il file è ordinato come gli altri?

1 · I nomi

Un nome dice cosa c'è dentro la variabile, o cosa fa la funzione. Se una variabile ha bisogno di un commento per essere capita, il nome è sbagliato.

Python
t = 0        # minuti di ritardo totali   <- il commento fa il lavoro del nome
ritardo_totale = 0

I nomi in questo libro sono in italiano, come nel resto del sito. Una lettera sola va bene solo in due casi ristretti: un contatore di cicli piccolissimo, o una formula matematica. Altrove, no.

Evita anche i nomi vaghi: dati, roba, tmp, res, calc, fai. Sembrano nomi, ma non dicono niente. Una funzione si chiama con un verbo (minuti_extra, compenso_straordinari), una variabile con un sostantivo (compenso, righe).

2 · Una funzione, un compito

Se per dire cosa fa una funzione ti serve una «e», sono due funzioni.

Python
def leggi_e_calcola(percorso):       # «legge E calcola»: due compiti
    ...

def leggi_righe(percorso):           # un compito
    ...

def media_ritardo(minuti):           # un altro compito
    ...

Una funzione che calcola restituisce il risultato con return: non stampa e non legge file. Una funzione che stampa si limita a stampare. Così la stessa funzione che calcola puoi riusarla, e provarla da sola.

Quando le funzioni sono tante, si dividono in file. Un file (un modulo) per argomento: uno che calcola, uno che stampa. Chi stampa importa chi calcola, come hai visto in Moduli e file.

Python
# ritardi_calcolo.py
def media_ritardo(minuti: list[int]) -> float:
    return sum(minuti) / len(minuti)
Python
# ritardi_stampa.py
from ritardi_calcolo import media_ritardo

print(f"Media: {media_ritardo([2, 0, 7, 11]):.1f} minuti")

Quanto deve essere lunga una funzione? Non c'è un numero giusto. Un'idea pratica: se non entra in una schermata, o se non riesci a dire cosa fa in una frase, è troppo.

3 · Niente numeri magici

Un numero magico è un numero scritto dentro il codice senza un nome. Compare così, dal nulla, e nessuno sa perché sia proprio quello. Lo scrivi una volta sola, in cima al file, in MAIUSCOLO: una costante.

diff
-    if ritardo > 5:
+    if ritardo > MINUTI_DI_TOLLERANZA:
Python
MINUTI_DI_TOLLERANZA = 5

Due vantaggi: chi legge capisce cos'è il 5, e se la tolleranza cambia la cambi in un posto solo. Lo 0 e l'1 (il punto di partenza di un contatore, il passo di un ciclo) si lasciano scritti come sono. Il nome deve dire cosa misura, non solo che è un numero: MINUTI_DI_TOLLERANZA, non CINQUE e nemmeno COSTANTE_1.

4 · Gli errori non si nascondono

È la regola che costa di più, quando la rompi. Ecco except da solo, e except con un pass dentro:

Python
try:
    totale = totale + int(riga.split(",")[1])
except:
    pass

Questo except prende tutti gli errori, anche i tuoi bug: un nome scritto male, una funzione che non esiste. Il programma non si ferma, il risultato è sbagliato, e non c'è nessun messaggio da leggere. Un bug che fa rumore lo trovi in un minuto, uno silenzioso in una settimana. (Ne parla anche I bug silenziosi.)

Hai due strade oneste.

Gestire l'errore che ti aspetti, dicendo cosa è successo, su stderr (come in Moduli e file):

Python
try:
    totale = totale + int(riga.split(",")[1])
except ValueError:
    print(f"Riga {numero_riga} ignorata: {riga}", file=sys.stderr)

Nell'except il tipo dell'errore che ti aspetti, ValueError; e dentro, almeno un avviso. Se arriva un altro errore, quello vero, il programma si ferma e il traceback lo dice.

Segnalare a chi ti chiama che qualcosa non va, con raise:

Python
def prezzo_corsa(zone: int) -> float:
    if zone < 1:
        raise ValueError(f"Le zone sono almeno 1, non {zone}")
    return zone * PREZZO_PER_ZONA

Chiamata con 0, la funzione si ferma e scrive:

ValueError: Le zone sono almeno 1, non 0

Il messaggio dice cosa non va e con che valore. Come funzionano try, except e raise per intero lo trovi in try, except, raise.

5 · Non ripeterti

Due pezzi quasi uguali, uno copiato e incollato dall'altro con un nome cambiato, sono una trappola: un giorno cambi un pezzo e dimentichi l'altro. Dove vedi un copia e incolla, c'è sempre una di queste quattro cure:

Il copia e incollaLa cura
lo stesso blocco con un valore diversouna funzione con un parametro
lo stesso blocco ripetuto per una lista di coseun ciclo
tanti if che associano una cosa a un'altraun dizionario
un if chiave in dizionario seguito da un valore di ripiegoget

Vale anche per i testi: una scritta che compare in tre punti si scrive una volta sola, in una costante.

6 · Commenti sul perché, non sul cosa

Il codice dice già cosa fa. Quello che non può dire è perché.

Python
# sommo i minuti al totale          <- ovvio, lo dice la riga sotto
totale = totale + minuti

# i treni T hanno due piani: il regolamento richiede un secondo ispettore
if treno.startswith("T"):
    minuti = minuti * DOPPIO_CONTROLLO

Un commento sul cosa è rumore, e peggio: invecchia. Quando cambi il codice dimentichi di cambiare il commento, e adesso mente. Un commento sul perché resta vero finché resta vera la ragione. Scrivilo sulle righe strane, sulle scelte che sembrano sbagliate, sulle regole che vengono da fuori (un regolamento, un cliente, un bug di un altro programma).

Per le funzioni c'è la docstring, quella che hai visto in Le funzioni: una frase che dice a cosa serve.

7 · La forma

Il codice si legge più in fretta quando ha sempre la stessa faccia: rientri uguali, spazi uguali, righe non troppo lunghe, tipi dichiarati. Ci sono tre cose, e le prime due le fa un programma al posto tuo.

I type hints dicono che tipo entra e che tipo esce (minuti: int, -> float), come in Le funzioni. L'estensione Pylance di VS Code li usa per avvisarti se passi un testo dove serve un numero.

PEP 8 è la guida di stile ufficiale di Python: nomi in minuscolo con il trattino basso, due righe vuote fra le funzioni, niente == None. Nessuno la ricorda a memoria: la ricordano i programmi.

Ruff è quel programma. Fa due mestieri diversi:

  • il linter (ruff check) legge il codice e dice cosa non va: un import mai usato, un == None, un tipo mancante;
  • il formattatore (ruff format) riscrive il file con la stessa impaginazione per tutti.

Prendiamo un file di Ivo, impaginato a caso:

Python
import os
import sys


def ritardo_medio(minuti,giorni):
    l = [m for m in minuti]
    if giorni == None: return 0
    totale=sum(l)
    return totale/giorni
Terminale
ruff check --output-format concise orari_ivo.py
orari_ivo.py:1:8: F401 [*] `os` imported but unused
orari_ivo.py:2:8: F401 [*] `sys` imported but unused
orari_ivo.py:5:5: ANN201 Missing return type annotation for public function `ritardo_medio`
orari_ivo.py:5:19: ANN001 Missing type annotation for function argument `minuti`
orari_ivo.py:5:26: ANN001 Missing type annotation for function argument `giorni`
orari_ivo.py:6:5: E741 Ambiguous variable name: `l`
orari_ivo.py:7:18: E711 Comparison to `None` should be `cond is None`
orari_ivo.py:7:22: E701 Multiple statements on one line (colon)
Found 8 errors.
[*] 2 fixable with `--fix` (1 unsafe fix available with `--fix --unsafe-fixes`).

Ogni riga è: file, riga, colonna, codice della regola, cosa non va. Il codice (E741, F401...) lo puoi cercare in rete, o nella pagina Se qualcosa va storto. Un solo messaggio, in forma lunga, per vedere cosa c'è dietro:

E741 Ambiguous variable name: `l`
 --> orari_ivo.py:6:5
  |
5 | def ritardo_medio(minuti,giorni):
6 |     l = [m for m in minuti]
  |     ^
7 |     if giorni == None: return 0
8 |     totale=sum(l)
  |

Poi il formattatore:

Terminale
ruff format orari_ivo.py
1 file reformatted

Il file è diventato:

Python
import os
import sys


def ritardo_medio(minuti, giorni):
    l = [m for m in minuti]
    if giorni == None:
        return 0
    totale = sum(l)
    return totale / giorni

Ha sistemato spazi e righe, ma non ha toccato l, == None, gli import e i tipi: quelli sono scelte di chi scrive, e li dice il linter. I due strumenti si completano: prima ruff format, poi ruff check e correggi a mano quello che resta.

In VS Code, con l'estensione Ruff, le segnalazioni compaiono sottolineate mentre scrivi, e Format Document (Shift+Option+F su Mac, Shift+Alt+F su Windows) impagina il file. L'estensione si installa come hai visto in VS Code per Python.

Ricorda

  • Il codice si scrive per chi lo legge: tra tre mesi sei tu.
  • Nomi: dicono cosa contengono. Niente t, x, tmp.
  • Una funzione, un compito: se serve una «e», sono due. Chi calcola non stampa. Funzioni tante: file diversi.
  • Niente numeri magici: una costante in maiuscolo, in cima al file.
  • Gli errori non si nascondono: mai except: da solo, mai pass. O gestisci (except ValueError: e un avviso su stderr) o segnali (raise ValueError(...)).
  • Non ripeterti: un copia e incolla chiede una funzione, un ciclo, un dizionario o get.
  • Commenti sul perché, non sul cosa.
  • Forma: type hints, PEP 8, e Ruff che controlla (ruff check) e impagina (ruff format).