Revisione del codice: metodi e strumenti

La revisione del codice è parte integrante dello sviluppo software moderno e permette agli altri membri del team di programmazione di scoprire errori e migliorare la qualità del codice. A questo scopo vengono utilizzate diverse tecniche e approcci, che presentiamo in dettaglio di seguito.

La revisione del codice, conosciuta in inglese come “Code Review”, è una misura di garanzia della qualità nello sviluppo software. Il codice sorgente è il mezzo di base del lavoro di sviluppo e il prodotto principale della programmazione. Il codice appena creato o modificato viene sottoposto a una revisione del codice. In questo processo, uno o più membri del team rivedono il lavoro di un programmatore.

Un progetto software comprende un “codebase”, ovvero una raccolta di file di codice che insieme servono a fornire un prodotto. Qui è incluso il codice del prodotto vero e proprio, la configurazione, gli strumenti di sviluppo, i test e altro ancora, tutti mappati nel codice. L’intero codebase è gestito con un sistema di controllo delle versioni come Git. Diverse versioni del codebase possono essere gestite in parallelo attraverso diversi “branches”, “rami” in italiano. Ciò consente di sviluppare nuove funzionalità senza modificare la versione di produzione del codebase.

Il lavoro di sviluppo si svolge solitamente nei cosiddetti Feature-Branches (“rami di funzionalità”), che vengono periodicamente integrati nel Main-Branch (“ramo principale”). La revisione del codice viene eseguita prima del “merge”, cioè prima che il codice nuovo o modificato venga unito al codebase esistente. L’obiettivo è quello di individuare ed eliminare i bug nelle fasi iniziali, prima che il codice venga messo in produzione.

Ma l’eliminazione dei bug non è l’unico vantaggio della revisione del codice. Che il codice funzioni, cioè che venga eseguito senza errori e raggiunga il risultato desiderato, è solo un requisito fondamentale. Oltre a ciò, esistono una moltitudine di altri criteri di qualità per il codice pulito, conosciuto anche come Clean Code. La presenza di commenti, la chiarezza e la coerenza del codice, il rispetto delle linee guida di stile e l’integrabilità nei sistemi esistenti sono tutti elementi critici che vengono presi in considerazione durante la revisione del codice.

Poiché la maggior parte del lavoro di sviluppo si svolge in gruppi, gli effetti della revisione del codice vanno oltre la pura qualità del codice. Questo perché la revisione del codice viene effettuata da altri membri del team di sviluppo e genera effetti sociali: i nuovi membri ricevono un feedback sulle convenzioni e sulle migliori pratiche, le conoscenze vengono scambiate e distribuite all’interno dell’organizzazione. In questo modo, la revisione del codice contribuisce a promuovere una cultura della qualità.

Anche se effettuati da persone, i processi di revisione del codice sono oggi generalmente supportati da strumenti speciali. Gli strumenti di revisione del codice risultano efficienti e permettono alle persone coinvolte di impiegare meno tempo nel coordinamento dei processi. In questo modo le persone possono concentrarsi sulla revisione vera e propria del codice.

Concettualmente, la revisione del codice da parte dell’uomo si colloca tra due metodi di analisi automatizzata, l’analisi statica e quella dinamica. Le differenze in sintesi:

Il concetto di revisione del codice è semplice: il codice modificato o scritto di recente viene controllato per verificarne la correttezza da parte di uno o più membri del team di sviluppo (chiamati “revisori”). I revisori leggono il codice e identificano eventuali errori e variazioni dalle convenzioni stabilite nel team. I revisori migliorano il codice contestualmente oppure trasmettono le loro scoperte agli autori originali, che incorporano le modifiche.

Per quanto l’idea sia semplice, nella pratica l’impegno necessario per i processi di revisione del codice aumenta rapidamente. Tuttavia, il diavolo è nei dettagli: quali modifiche vengono fatte insieme e come vengono comunicate ai revisori? In che modo gli errori e i commenti trovati vengono assegnati ai punti appropriati del codice e resi disponibili ai responsabili del miglioramento? Senza strumenti specifici di revisione del codice, si riescono a coordinare questi passaggi solo all’interno di team molto piccoli.

Nei team di programmazione distribuiti e agili, la revisione del codice è solitamente parte integrante del processo di sviluppo. Nel contesto della Continuous Integration (CI), il codice viene continuamente scritto, testato e mantenuto nel codebase esistente. La revisione del codice da parte di un umano fa parte della pipeline di CI automatizzata che ogni unità di codice attraversa. Solo quando tutti i test vengono superati, il codice viene integrato e successivamente inviato ai sistemi di produzione.

Qui di seguito diamo un’occhiata alle singole fasi di una pipeline di CI e alla posizione della revisione del codice in essa contenuta:

1. Scrivere il codice

1. Scrivere il codice nel Feature-Branch
2. Test del codice in ambiente locale

2. Integrare il codice nel codebase

1. Analizzare e formattare automaticamente il codice nel Feature-Branch
2. Rivedere il codice e aggiungere miglioramenti
3. Unire il codice nel Main-Branch
4. Distribuire e testare il Main-Branch sul sito di staging

3. Mettere il codice in produzione

1. Unire il codice nel Release-Branch
2. Passare dal Release-Branch al sito live

La revisione del codice è una parte importante del controllo di qualità nello sviluppo software. Pertanto, la revisione del codice assicura che il codice appena scritto sia il più possibile privo di errori e soddisfi gli standard di qualità dell’organizzazione. A lungo termine, questo riduce al minimo il debito tecnico; a breve termine, impedisce che il codice difettoso venga eseguito sui sistemi di produzione.

Il codice è un mezzo potente; una volta scritto, lo stesso codice viene eseguito più volte o contemporaneamente in più istanze. In questo modo, gli errori provocano un “effetto a catena”, in cui piccoli errori in una posizione centrale hanno un grande impatto sull’intero sistema. Pertanto, di solito è molto più costoso correggere gli errori nel codice già in esecuzione nel sistema di produzione piuttosto che correggerli in anticipo.

La revisione del codice aiuta a livellare le differenze di qualità tra le diverse parti del codebase. Questo perché la qualità del codice varia notevolmente a seconda delle circostanze in cui è stato scritto. I seguenti fattori abbassano la qualità dello sviluppo del codice di un programmatore o di una programmatrice:

• mancanza di esperienza di programmazione
• scarsa conoscenza del sistema
• mancanza di familiarità con le convenzioni del team
• stress durante lo sviluppo
• sviluppo sotto pressione
• esaurimento mentale

Oggi l’uso del codice va oltre la scrittura di programmi. Questo perché il codice è un mezzo espressivo che si presta alla descrizione precisa di sistemi di ogni tipo. Ad esempio, esso viene utilizzato per realizzare contratti intelligenti basati su blockchain o per definire ambienti cloud tramite Infrastructure-as-Code. Anche per questi approcci si può utilizzare una revisione del codice.

Le migliori pratiche qui presentate provengono da un ampio studio empirico condotto da Smart Bear su un team di programmazione Cisco. In parte, queste riflettono i limiti dei revisori umani. Il codice è un mezzo complesso che richiede molta attenzione nella revisione. Gli esseri umani hanno una capacità mentale limitata che si esaurisce man mano che viene sottoposta a uno sforzo costante. Se manca l’attenzione, è facile che gli errori sfuggano e che il tempo dedicato alla revisione del codice vada sprecato.

Inoltre, queste pratiche mirano a garantire che i processi di revisione del codice siano in linea con gli obiettivi. Se si riscontrano errori, è necessario correggerli. Ciò richiede responsabilità chiare e modalità di gestione dei processi e di monitoraggio dei progressi. Diamo un’occhiata alle migliori pratiche che abbiamo trovato:

• Controllate un massimo di 400 righe di codice per sessione: elaborando grandi quantità di codice, è facile che gli errori sfuggano.
   
• Non rivedete più di 500 righe di codice all’ora: in caso contrario, la capacità dei revisori di individuare gli errori ne risente.
   
• Limitate le revisioni del codice a un massimo di 60 minuti: se si protraggono più a lungo, i revisori perdono la concentrazione necessaria.
   
• Stabilite gli obiettivi e registrate le metriche: quanti errori vengono trovati per unità di tempo o per righe di codice?
   
• Gli autori del codice devono annotare il codice sorgente prima della revisione: le annotazioni guidano i revisori nelle modifiche al codice e le spiegano.
   
• Utilizzate liste di controllo: devono contenere gli elementi che vengono presi in considerazione durante ogni revisione.
   
• Stabilite un processo per correggere gli errori riscontrati: non è sufficiente limitarsi a rilevare gli errori. Sono necessarie linee guida e strutture chiare per correggere gli errori.
   
• Promuovete una cultura positiva della revisione del codice: gli errori non devono essere presentati come una colpa personale, ma come un’opportunità per imparare.
   
• Sfruttate le implicazioni inconsce di una revisione tra pari: se si sa che il codice è soggetto a revisione, i programmatori si impegnano di più.
   
• Scegliete processi di revisione del codice leggeri: i moderni strumenti di revisione del codice hanno reso efficiente questa fase.

In generale, la revisione del codice è considerata una parte essenziale dello sviluppo software. Questo perché i vantaggi della revisione del codice sono evidenti. Tuttavia, il suo utilizzo comporta anche alcuni svantaggi. Vediamo i vantaggi e gli svantaggi della revisione del codice.

Il vantaggio principale della revisione del codice è quello di individuare ed eliminare gli errori in anticipo, prima che causino conseguenze negative. Si tratta di un approccio molto più efficiente rispetto alla rilevazione e correzione degli errori in un momento successivo del ciclo di vita del codice. Se il codice difettoso fa già parte di un sistema di produzione, altri componenti possono basarsi su di esso, rendendo più difficili i miglioramenti.

Ma i vantaggi di una regolare revisione del codice vanno oltre la ricerca di singoli errori. In particolare, è importante considerare il processo nel suo insieme: come si inserisce il codice nel codebase? Le revisioni continue del codice aiutano a identificare gli schemi generali e a definire gli standard. Oltre agli errori funzionali, vengono identificati e affrontati code smell. Se necessario, si ricorre al refactoring e a design pattern per creare omogeneità tra più componenti.

Le revisioni del codice coinvolgono i membri del team di programmazione e li mettono in comunicazione tra loro. Perciò non sorprende che i processi consolidati di revisione del codice contribuiscano ad aumentare le competenze di codifica del team. Infatti, le revisioni del codice legano e distribuiscono le conoscenze all’interno del team e migliorano le capacità di codifica dei singoli membri.

A livello organizzativo, le revisioni del codice aiutano a stabilire una cultura della qualità. Quando si sa che il proprio lavoro viene ricontrollato, si tende a impegnarsi di più. Per ottenere l’effetto desiderato, è sufficiente sottoporre a revisione circa un terzo del codice prodotto.

Naturalmente, una revisione del codice comporta un maggiore sforzo per l’organizzazione, dato che costa tempo e impegna il personale, senza contare che sono necessarie risorse per gestire i processi coinvolti. Tuttavia, i costi da sostenere servono ad aumentare la qualità del codice. Non bisogna dimenticare che la mancanza di qualità causa costi considerevoli.

Senza strumenti di supporto per la revisione del codice, questa può risultare molto inefficiente. Ciò era particolarmente problematico con i metodi tradizionali prima che si diffondesse la revisione leggera del codice. In ogni caso, sono necessari obiettivi e finalità chiare per questi processi. In questo modo, lo sforzo e i benefici sono calcolabili, evitando così di rimanere in un limbo.

Per quanto riguarda gli sviluppatori, le revisioni del codice dovrebbero portare a un aumento delle conoscenze e della coesione del team. A tal fine è importante un ambiente costruttivo e amichevole. Se durante una revisione del codice si verificano ostilità o recriminazioni, ciò può essere traumatico per le persone coinvolte. I nuovi arrivati nel team, i membri di minoranze e i programmatori e le programmatrici relativamente inesperte ne sono particolarmente colpiti.

La prima forma di revisione del codice era nota come “ispezione Fagan”. Si è trattato di un processo elaborato che ha richiesto quattro persone e la stampa del codice su carta, oltre a diverse riunioni. Pur essendo efficace per trovare i bug, questo metodo è impossibile da integrare nel moderno lavoro di sviluppo agile.

In contrasto con la complessa ispezione Fagan, oggi si utilizzano approcci leggeri alla revisione del codice, che coinvolgono l’autore o l’autrice del codice e uno o più revisori.

Il metodo “over the shoulder” è la forma più semplice di revisione del codice. L’autore o l’autrice presenta il codice scritto a un altro membro del team di sviluppo (revisore). Oltre alla ricerca degli errori, vengono discusse le strutture del codice e spiegati gli approcci alternativi. La comunicazione diretta tra la persona che presenta e il revisore consente un feedback rapido e l’immediata incorporazione dei miglioramenti.

La revisione del codice “over the shoulder” avviene in loco, sul proprio computer. Il collega o la collega guarda alle vostre spalle mentre presentate il codice. Ciò consente di utilizzare tutte le risorse e gli strumenti presenti sulla macchina di sviluppo. Una revisione di questo tipo è semplice e può essere effettuata ad hoc.

Concettualmente simile alla revisione del codice “over the shoulder” è la revisione del codice attraverso pair programming. Anche in questo caso, sono coinvolti due membri del team di programmazione. La differenza sta nella tempistica dei processi di creazione e revisione del codice. Mentre la revisione del codice “over the shoulder” avviene dopo la creazione del codice, nella programmazione in coppia entrambi i processi sono intrecciati.

Durante la programmazione in coppia, una persona, detta “driver”, scrive il codice e si occupa dei dettagli dell’implementazione. L’altra persona, nota come “reviewer”, controlla il codice scritto e fornisce un feedback. Il revisore tiene d’occhio anche il processo nel suo insieme: il codice non solo deve essere privo di errori e funzionare da solo, ma deve anche seguire i modelli e le regole di tutti i progetti.

È importante che driver e reviewer si scambino regolarmente i ruoli. In questo modo, c’è un’alternanza di prospettive, che bilancia l’equilibrio di potere e dà a entrambe le persone l’opportunità di recuperare mentalmente. Inoltre, al partecipante con meno esperienza viene data la possibilità di imparare in entrambi i ruoli.

Le modifiche o l’aggiunta di nuovo codice in progetti di grandi dimensioni richiedono spesso la revisione del codice da parte di più persone. La revisione del codice tramite notifica per e-mail consiste nell’invio di un riepilogo delle modifiche a tutte le persone coinvolte. Seguono diversi cicli di discussione con scambio di e-mail e l’integrazione delle modifiche fino al completamento della revisione e alla finalizzazione del codice.

Come è facile immaginare, con un gran numero di collaboratori, il processo rischia di diventare rapidamente confuso. Pertanto questo metodo di notifica per e-mail funziona meglio con il supporto di strumenti di revisione del codice appropriati.

Gli approcci moderni alla revisione del codice utilizzano strumenti specifici per la revisione del codice. Questi strumenti strutturano i processi di revisione, creano efficienza e raccolgono metriche; quindi rendono il processo di revisione pianificabile, controllabile e verificabile.

Esiste un’ampia gamma di strumenti per la revisione del codice. Alcuni di questi sono integrati negli approcci esistenti per la Continuous Integration o la Continuous Delivery (CI/CD). Vi presentiamo i diversi tipi di strumenti con alcuni esempi.

I sistemi di controllo di versione distribuiti (“Distributed version control systems”, DVCS) e in particolare l’onnipresente Git costituiscono la base degli strumenti per la revisione del codice. Includono la funzionalità di tracciare le modifiche al codice e di renderle visibili come “diff”. Le piattaforme basate su Git, come GitHub e GitLab, migliorano la visibilità e si concentrano sul lavoro in team. Con le loro merge requests, queste piattaforme forniscono una revisione del codice integrata prima di accettare nuovo codice.

Questi strumenti si basano su Git o un altro sistema di controllo di versione distribuito (DVCS). Su questa base, per organizzare le revisioni del codice all’interno del team viene solitamente utilizzata un’interfaccia utente basata sul web. Alcuni strumenti di revisione del codice hanno anche una propria interfaccia a riga di comando (Command line interface, CLI).

GitHub si è affermato come piattaforma standard per l’amministrazione sul web dei repository Git. Il meccanismo principale per la revisione del codice è costituito dalle cosiddette pull requests. Se si desiderano apportare modifiche al codice di un repository, si segue un semplice schema:

1. Clonare il repository come copia locale
2. Apportare modifiche al proprio branch
3. Creare una pull request: si chiede ai manutentori del repository di rivedere le modifiche e, se sono positive, di unirle al repository principale (funzione “merge”)

Lo strumento per la revisione del codice Review Board mette in primo piano le richieste di revisione. L’interfaccia web moderna e user-friendly fornisce un riepilogo di tutte le richieste di revisione in corso nei repository e nei branch. Il comando dedicato rbt consente un accesso rapido dalla riga di comando. Oltre al codice, anche i grafici e i documenti PDF possono essere inclusi nei processi di revisione.

Gerrit è impostato sul proprio server e funge da interfaccia tra le modifiche al codice e il codebase di produzione. Le modifiche sono verificate dalla revisione del codice e vengono messe in produzione solo se superano il controllo. Un’installazione di Gerrit comprende un ambiente Git self-hosted con accesso SSH e un’interfaccia web disponibile tramite HTTPS. Oltre alle notifiche facoltative per e-mail, il programma include un sistema di votazione delle modifiche al codice.

Lo strumento per la revisione del codice Code Collaborator di Smart Bear mette in primo piano le storie degli utenti. Si tratta di specifiche di funzionalità incentrate sull’utente che vengono tradotte in codice e convalidate attraverso i test. Lo strumento coinvolge il team di programmazione, i manager e i team di test e consente una revisione coerente delle modifiche alle storie utente, al codice e ai piani di test.

Questi strumenti, noti come “linter”, vengono utilizzati per analizzare e formattare automaticamente il codice in preparazione alla revisione del codice. Tecnicamente, si tratta di un’analisi statica perché il codice viene letto ma non eseguito. I linter sono utilizzati come parte della pipeline CI per standardizzare la formattazione del codice o per adattare il codice alle specifiche di stile.

L’analisi statica fornisce anche metriche sul codice, come il numero di righe (“Lines of code”, LOC) per file, classe o funzione. Grazie a questi è possibile anche rilevare gli errori più comuni prima della revisione umana del codice, tra cui errori di digitazione, iniezioni SQL ed errori out-of-bounds.

Questi strumenti, relativamente nuovi, funzionano concettualmente come un editor di codice basato sul web con la sincronizzazione delle modifiche tra più utenti. Consentono la programmazione in coppia in ambienti distribuiti e permettono revisioni del codice “over the shoulder” indipendentemente dalla propria posizione geografica. Soprattutto dopo la pandemia da coronavirus, questi strumenti sono diventati molto popolari.

Sia Replit, uno strumento basato sul web, che LiveShare, integrato nell’editor VSCode di Microsoft, possono essere utilizzati come editor HTML collaborativi. Naturalmente, entrambi gli strumenti sono in grado di gestire altri linguaggi e consentono di collaborare lavorando su più file e persino di eseguire codice.