Nel lavoro quotidiano di uno sviluppatore senior, la revisione del codice (PR Review) è una delle attività più strategiche e frequenti. Non si tratta solo di approvare righe di codice, ma di contribuire attivamente alla qualità complessiva del software, migliorando leggibilità, manutenibilità e coerenza dell’intero progetto.
Questa guida raccoglie alcuni dei principi da tenere sempre a mente per effettuare revisioni efficaci e per scrivere codice pulito in modo naturale durante lo sviluppo. Per chi non l’abbia fatto consiglio la lettura di clean code
Uno dei libri a mio avviso fondamentali che un developer dovrebbe leggere. Molte delle “regole” che suggerisco vengono da questo libro.
1. Nomi che Parlano da Soli
- Rendi esplicito lo scopo: nomi di variabili, metodi e classi devono chiarire subito cosa fanno o cosa rappresentano.
- Usa verbi per i metodi e sostantivi per le classi.
- Un termine per ogni concetto: non alternare
get,retrieve,fetchper la stessa azione. - Evita abbreviazioni criptiche: il codice dovrebbe essere leggibile anche a distanza di mesi.
- Usa nomi ricercabili: evita lettere singole o sigle oscure che rallentano la navigazione nel codice.
2. Funzioni Pulite
- Devono essere brevi: più il blocco cresce, più diventa difficile da capire e testare.
- Una sola responsabilità: se un metodo fa più cose, va diviso.
- Livello di astrazione costante: evita di mescolare dettagli bassi (es. logica di formattazione) con concetti di alto livello (es. logica di business).
- Ordine leggibile: il codice dovrebbe “leggersi come un libro”, con i dettagli in fondo.
- Numero di parametri ridotto: massimo tre; se servono di più, considera un oggetto wrapper.
- Nessun effetto collaterale: una funzione deve fare una cosa e farla bene, senza modificare lo stato globale.
3. Commenti: Meno è Meglio
- Il codice è il tuo miglior commento: punta alla massima espressività nel codice stesso.
- Scrivi commenti solo quando servono davvero, ad esempio:
- Per segnalare workaround temporanei
- Per chiarire logiche complesse
- Per avvisi o limitazioni
- Evita commenti ridondanti: se un metodo si chiama
calcolaTotale(), non serve scrivere// Calcola il totale. - I TODO devono essere azionabili e facilmente ricercabili.
4. Formattazione Coerente
- Organizza verticalmente il codice: metti vicini i metodi correlati.
- Mantieni le classi compatte: idealmente sotto le 300 righe.
- Ordina logicamente variabili e metodi: dichiarazioni in alto, utilizzi in basso.
- Evita righe orizzontali troppo lunghe che costringono a scrollare lateralmente.
- Segui le convenzioni del team: l’uniformità vale più del gusto personale.
5. Dati e Oggetti
- Non esporre dettagli interni: un modulo deve sapere il meno possibile sullo stato interno degli altri oggetti.
- Utilizza DTO (Data Transfer Object) per scambiare dati tra livelli, ma senza logica.
- Scegli consapevolmente tra approccio procedurale e orientato agli oggetti: il primo è flessibile per funzioni, il secondo per tipi.
6. Gestione degli Errori
- Usa eccezioni, non flag o
null. - Dai contesto agli errori: includi messaggi esplicativi, parametri coinvolti e cause potenziali.
- Evita il
try-catchsilenzioso: logga sempre l’errore, anche se viene gestito. - Mai restituire
null, mai accettarenullcome parametro senza validazione.
7. Unit Test Efficaci
- Scrivi i test prima del codice (TDD), almeno per i casi critici.
- Un solo
assertper test, o comunque un solo concetto testato alla volta. - Mantieni i test leggibili, veloci e indipendenti.
- Ogni test deve essere eseguibile in isolamento, più volte e in qualsiasi ordine.
- Evita test fragili e basati su dati esterni o randomici.
8. Classi Pulite
- Rispetta il principio di responsabilità singola (SRP): una classe, un compito.
- Alta coesione: i metodi devono lavorare sugli stessi dati.
- Bassa accoppiatura: una classe dovrebbe sapere poco o nulla di come funzionano le altre.
- Non aggiungere metodi “just in case”: ogni metodo deve avere uno scopo chiaro.
Conclusione
Scrivere e revisionare codice pulito non è solo una buona pratica: è una responsabilità. Ogni PR è un’opportunità per costruire software più solido, leggibile e longevo. Serve inoltre ad instaurare un dialogo costruttivo all’interno del team sul rispetto degli standard e su un modo comune di scrivere il codice.
Un team che adotta questi principi riduce i bug, accelera il time-to-market e rende più semplice l’onboarding di nuovi sviluppatori.
La qualità non si corregge a fine progetto. Si costruisce ogni giorno, una PR alla volta.