Code review: come revisionare il codice di qualcun altro

Scrivere una buona proposta di modifica è metà del lavoro; l'altra metà è saperla revisionare. È una competenza che nessuno insegna: al primo lavoro ti arriva una richiesta di revisione e ti arrangi, con il risultato che si oscilla tra l'approvare tutto senza guardare e il commentare ogni parentesi. In questo articolo trovi come si fa una revisione che serve davvero.

Questo articolo guarda dal lato di chi revisiona. Il lato di chi propone — come confezionare una modifica revisionabile — è in cos'è una pull request.

A cosa serve davvero

Vale la pena essere precisi, perché determina cosa guardare.

Trovare bug non è lo scopo principale. I test automatici ne intercettano di più e prima. Una revisione umana ne trova alcuni, ma non è lì il valore.

Le tre cose che la revisione fa e nient'altro può fare:

Diffondere la conoscenza. Se una sola persona sa come funziona una parte del sistema, quella parte è a rischio quando va in ferie o cambia lavoro.

Mantenere la coerenza. È il meccanismo attraverso cui codice scritto da cinque persone continua a sembrare scritto da una.

Far crescere le persone. Per chi è all'inizio è il canale di apprendimento più efficace che esista: qualcuno di più esperto guarda il tuo codice concreto e ti dice cosa migliorare.

Se pensi alla revisione come a una caccia agli errori, la farai male. È soprattutto un trasferimento di contesto tra persone.

Cosa guardare, in ordine

L'ordine conta, perché parte del tempo si spreca commentando dettagli su codice che andava ripensato.

1. Il problema è quello giusto? Questa modifica risolve davvero il problema dichiarato? Se la risposta è no, tutto il resto è irrilevante — ed è il commento più importante che puoi fare.

2. L'approccio regge? Ci sono soluzioni più semplici? Va nella direzione del resto del sistema? Questo va detto subito: commentare l'architettura dopo che la persona ha rifinito ogni dettaglio significa buttare il suo lavoro.

3. I casi limite. Cosa succede con input vuoto, valori nulli, liste enormi, chiamate che falliscono? È qui che una revisione umana batte davvero i test.

4. La sicurezza. Input validati? Query costruite in modo sicuro? Dati sensibili nei log? Permessi verificati lato server e non solo nell'interfaccia? Credenziali finite nel codice per sbaglio — che è un problema serio, come spiego in file .gitignore.

5. La leggibilità. Un'altra persona capirà questo codice tra sei mesi? Nomi comprensibili, funzioni che fanno una cosa sola.

6. I test. Ci sono? Provano il comportamento o solo l'implementazione?

7. Lo stile. Per ultimo, e possibilmente mai: dovrebbe occuparsene un formattatore automatico, fatto girare nei controlli automatici. Se il tuo team discute di indentazione nelle revisioni, il problema è la mancanza di uno strumento, non le persone.

Come scrivere i commenti

Qui si decide se il processo funziona o avvelena il team.

Fai domande invece di dare ordini.

❌ "Usa una mappa qui." ✅ "C'è un motivo per usare un array? Con una mappa la ricerca sarebbe più diretta."

La domanda apre una conversazione e lascia spazio al fatto che l'altra persona possa avere ragione. L'ordine chiude.

Distingui il vincolante dal preferibile. È la pratica singola che migliora di più le revisioni: usa un prefisso esplicito.

• bloccante: — va cambiato prima di integrare
• nit: — dettaglio, prendilo o lascialo
• domanda: — non capisco, spiegami
• idea: — non ora, ma da tenere presente

Senza questa distinzione, chi riceve venti commenti non sa quali deve assolutamente affrontare e quali sono opinioni.

Spiega il perché. "Questo va cambiato" costringe l'altro a indovinare. "Questo può andare in errore se l'elenco è vuoto" gli dice cosa fare.

Commenta il codice, non la persona. "Questa funzione fa troppe cose", non "scrivi funzioni troppo lunghe".

Riconosci le cose fatte bene. Un commento positivo su una soluzione elegante costa dieci secondi. Una revisione fatta solo di critiche è demoralizzante, e per chi è all'inizio fa una differenza enorme.

Gli errori che avvelenano il processo

Essere lenti. Una proposta ferma tre giorni blocca una persona. La tempestività conta più della profondità: una revisione parziale oggi vale più di una completa venerdì.

Approvare senza guardare. Se non hai tempo, dillo. Un'approvazione automatica è peggio di nessuna revisione, perché dà l'illusione del controllo.

Riscrivere il codice altrui nei commenti. Se stai dettando la tua soluzione riga per riga, non stai revisionando: stai scrivendo il codice attraverso qualcun altro.

Il "mentre ci sei". Chiedere di sistemare cose non correlate allunga la modifica e ne peggiora la revisionabilità. Aprine una separata — o annotala come debito tecnico da affrontare a parte.

Bloccare per gusto personale. Se il codice funziona ed è leggibile, il fatto che tu l'avresti scritto diversamente non è un motivo per rifiutare.

Commentare tutto con la stessa intensità. Venti commenti indistinti su una modifica producono paralisi.

Fare la revisione stanchi. Dopo la seconda ora si approva per esaurimento, che è come non revisionare.

Cosa fare se la modifica è troppo grande

Capita, e non c'è modo di revisionare bene 2.000 righe.

Dillo, invece di fingere. "Non riesco a revisionare questo in modo utile: possiamo spezzarlo?" è più onesto di un'approvazione di facciata.

Se non si può spezzare, dichiara cosa hai guardato: "Ho revisionato la logica dei pagamenti in dettaglio, il resto solo in superficie." Chi legge sa cosa è stato verificato e cosa no.

Un accorgimento pratico

Se i commenti superano i tre o quattro giri, smetti di scrivere e parla.

Le conversazioni scritte su questioni di architettura divergono facilmente: si accumulano fraintendimenti e il tono si irrigidisce senza che nessuno lo voglia. Dieci minuti a voce risolvono quello che venti commenti peggiorano.

Poi si riassume la conclusione nel commento, così resta traccia.

In sintesi

La revisione non serve principalmente a trovare bug — per quello ci sono i test. Serve a diffondere conoscenza, mantenere coerenza e far crescere le persone.

Si guarda in ordine: il problema è quello giusto, l'approccio regge, i casi limite, la sicurezza, la leggibilità, i test. Lo stile per ultimo, e possibilmente affidato a un formattatore automatico.

Sui commenti, due pratiche cambiano tutto: fare domande invece di dare ordini, e marcare cosa è bloccante e cosa è un dettaglio.

E l'errore che pesa più di ogni altro: essere lenti. Una revisione parziale oggi vale più di una perfetta tra tre giorni, perché nel frattempo qualcuno è fermo.