Code Review — cos'è, come funziona la revisione del codice e il controllo dei PR

Cos'è il Code Review

Code review è una verifica sistematica del codice da parte dei colleghi prima dell'integrazione. Nel contesto di Git, ciò significa: uno sviluppatore crea una pull request con le modifiche, assegna i revisori e questi studiano il diff, lasciano commenti ed emettono un verdetto. Un revisore può richiedere modifiche, approvare il PR o lasciare un commento generale.

La revisione del codice persegue cinque obiettivi: migliorare la qualità del codice (trovare difetti prima che arrivino in produzione), diffondere la conoscenza (il revisore apprende nuovi approcci, l'autore riceve feedback), garantire gli standard (verificare la conformità allo stile del codice e alle decisioni architetturali), ridurre il bus factor (più di uno sviluppatore conosce il codice) e costruire una cultura di responsabilità (l'autore scrive più attentamente sapendo che il codice verrà revisionato).

L'opposto della revisione del codice è un blind commit: uno sviluppatore invia modifiche a un ramo condiviso senza revisione. Questo approccio è accettabile solo in progetti mono-sviluppatore o per hotfix urgenti con revisione successiva. Nello sviluppo professionale in team, la revisione del codice è un passaggio obbligatorio per qualsiasi modifica, inclusi aggiornamenti di documentazione e configurazione.

Cosa controllare nel Code Review

La revisione del codice dovrebbe essere sistematica, non caotica. I revisori esperti controllano il codice in un ordine specifico: prima l'architettura e la logica, poi i test, poi la sicurezza e le prestazioni, e solo alla fine — lo stile e la denominazione. Questo ordine garantisce che i problemi critici vengano notati prima che il revisore si stanchi.

Architettura e logica: il codice risolve il compito, ci sono astrazioni eccessive, vengono rispettati i principi SOLID e DRY? Il codice complesso difficile da capire al primo sguardo è un segnale che è necessario un refactoring. Il revisore deve assicurarsi che il codice faccia esattamente ciò che il compito specifica e non abbia effetti collaterali al di fuori della propria responsabilità.

Test: i nuovi test coprono tutti gli scenari — positivi, negativi, casi limite. I test esistenti superano dopo le modifiche? Ci sono test flaky che falliscono in modo incoerente? Sicurezza: assenza di injection SQL, XSS, perdite di dati sensibili attraverso log o risposte API. Prestazioni: efficienza degli algoritmi, query eccessive al database, perdite di risorse.

• Architettura — correttezza della soluzione, conformità SOLID, assenza di over-engineering.
• Logica — gestione di tutti gli scenari, inclusi errori e casi limite.
• Test — copertura delle nuove modifiche, nessun test esistente rotto.
• Sicurezza — injection, XSS, CSRF, perdite di dati attraverso i log.
• Prestazioni — complessità degli algoritmi, query N+1, perdite di memoria.

Dimensione della revisione: perché 400 righe sono il massimo

Il limite di dimensione del PR è la metrica più importante dell'efficacia della revisione del codice. Uno studio di Cisco (2015) e i successivi esperimenti di SmartBear e Google hanno mostrato che quando il volume della revisione supera le 400 righe, la capacità del revisore di trovare difetti diminuisce drasticamente. Se un PR supera le 400 righe, i difetti vengono rilevati con una probabilità non superiore al caso.

Dimensione ottimale: 200–400 righe per PR. Questo volume può essere revisionato in 30–60 minuti mantenendo la concentrazione. Google raccomanda non più di 200 righe per round di revisione con concentrazione totale. Se le modifiche sono più grandi, il compito dovrebbe essere scomposto in più PR sequenziali, ciascuno dei quali introduce una modifica logicamente completa.

Tempo di revisione: entro 24 ore dalla creazione del PR. Se la revisione si protrae per diversi giorni, il contesto del compito viene perso e l'autore deve dedicare tempo a ripristinare il contesto quando risponde ai commenti. I team con una forte cultura di revisione del codice stabiliscono SLA: ad esempio, 4 ore per le modifiche critiche e 24 ore per quelle regolari.

Come scrivere buoni commenti di revisione

Il tono dei commenti è criticalmente importante per l'efficacia della revisione del codice. Un commento come “Questo è sbagliato” provoca una reazione difensiva e non fornisce informazioni utili all'autore. Una formulazione migliore è una domanda-suggerimento: “Cosa ne pensi di questo approccio?”, “Questo potrebbe causare un NPE se user == nil. Forse aggiungere un guard?”. Le domande sono meno conflittuali e stimolano la discussione.

Un buon commento include tre parti: cosa non va, perché è un problema e come risolverlo. Esempio: “Questo ciclo usa O(n²) a causa di un contains annidato, che potrebbe rallentare con 10k+ record. Prova a sostituirlo con un Set per la ricerca O(1).” Questa formulazione identifica simultaneamente il problema, spiega la sua importanza e suggerisce una soluzione — l'autore non deve indovinare.

GitHub e GitLab supportano i suggerimenti — proposte di modifica del codice inline. Un revisore può scrivere: “```suggestion Filter empty strings before processing```” e l'autore può applicare la modifica con un clic. Questo accelera le correzioni minori e riduce il numero di round di revisione. Per modifiche importanti, è meglio scrivere un commento generale piuttosto che incorporare grandi blocchi in un suggerimento.

# Modello per buon commento di code review

# MALE: "This code is wrong"
# BENE: "We may lose data on empty response.
#         If response.data == nil, the guard returns nil,
#         and user sees empty screen without error.
#         Maybe add a fallback error message?"

# Sintassi suggerimento GitHub:
# ```suggestion
# let result = try? parse(response, fallback: .defaultValue)
# ```

Flusso di lavoro del Code Review in team

Un flusso di lavoro efficace per la revisione si basa su quattro fasi. Prima — l'autore prepara il PR: scrive un titolo chiaro (ad esempio, “feat: add password reset screen”), aggiunge una descrizione delle modifiche, i link al compito nel tracker e le istruzioni di test. Seconda — l'autore assegna i revisori tramite auto-assign (basato su CODEOWNERS) o manualmente.

La terza fase — il revisore controlla il codice e lascia commenti. La quarta — l'autore apporta correzioni, risponde ai commenti e richiede una nuova revisione. Il ciclo si ripete fino all'approvazione. Dopo l'approvazione, l'autore esegue il merge (o il bot lo fa). L'automazione tramite Mergify o GitHub Auto-merge accelera la fase finale.

Un elemento importante del flusso di lavoro è la gestione dei PR in stallo. Se un PR rimane senza revisione per più di 3 giorni, il processo viene bloccato. Soluzioni: rotazione dei revisori (se il revisore assegnato non è disponibile), notifiche tramite Slack/Teams, limite di tempo per la revisione (SLA). In alcuni team, un PR senza revisione per più di 7 giorni viene chiuso automaticamente e l'autore ne crea uno nuovo dopo la sincronizzazione con main.

• Creazione del PR — titolo chiaro, descrizione, link al compito, screenshot per le modifiche UI.
• Assegnazione — auto-assegnazione tramite CODEOWNERS o selezione manuale di 1–2 revisori.
• Revisione — controllo nell'ordine: architettura → logica → test → sicurezza → stile.
• Correzioni — l'autore risponde a tutti i commenti, corregge i problemi bloccanti, richiede una nuova revisione.
• Merge — dopo l'approvazione e il CI verde, l'autore o il bot esegue il merge.

Errori comuni del Code Review

Il primo errore — revisione superficiale. Il revisore scansiona rapidamente il diff senza approfondire la logica e clicca Approva. Cause: PR grande, scadenza, stanchezza. Conseguenze: i bug arrivano in produzione. Soluzione: se non c'è tempo per una revisione di qualità — scrivi onestamente “Non posso revisionare oggi, spostalo a domani” invece di un'approvazione formale.

Il secondo errore — critica eccessiva (nitpicking). Il revisore lascia decine di commenti sullo stile di formattazione, sulla denominazione delle variabili, su dettagli banali. Questo demotiva l'autore e prolunga la revisione. Soluzione: StyleGuide e linter dovrebbero controllare lo stile automaticamente. L'umano nella revisione controlla logica, architettura e sicurezza.

Il terzo errore — revisione senza domande. Se il revisore pubblica solo Request Changes e Approve ma non fa domande, perde l'opportunità di imparare qualcosa di nuovo. Il miglior indicatore di una revisione sana è la presenza di discussioni in cui entrambe le parti imparano qualcosa di nuovo. Se una revisione è un monologo di un partecipante, il processo è rotto.

• Revisione superficiale — Approva senza analisi approfondita. Soluzione: non revisionare se non hai tempo.
• Nitpicking — criticare lo stile che dovrebbe essere controllato dal linter. Soluzione: automatizzare i controlli di stile.
• Preferenza personale — “L'avrei scritto diversamente”. Soluzione: il codice deve funzionare, non piacere al revisore.
• Ritardo — revisione più lunga di 24 ore. Soluzione: SLA sulla revisione, escalation in caso di violazione.
• Ignorare il contesto — revisionare il codice senza comprendere il compito. Soluzione: leggere la descrizione del PR prima del diff.