Revisione del codice: metodi e strumenti

La revisione del codice è parte in­te­gran­te dello sviluppo software moderno e permette agli altri membri del team di pro­gram­ma­zio­ne di scoprire errori e mi­glio­ra­re la qualità del codice. A questo scopo vengono uti­liz­za­te diverse tecniche e approcci, che pre­sen­tia­mo in dettaglio di seguito.

La revisione del codice, co­no­sciu­ta 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 prin­ci­pa­le della pro­gram­ma­zio­ne. Il codice appena creato o mo­di­fi­ca­to viene sot­to­po­sto a una revisione del codice. In questo processo, uno o più membri del team rivedono il lavoro di un pro­gram­ma­to­re.

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 con­fi­gu­ra­zio­ne, 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 at­tra­ver­so diversi “branches”, “rami” in italiano. Ciò consente di svi­lup­pa­re nuove fun­zio­na­li­tà senza mo­di­fi­ca­re la versione di pro­du­zio­ne del codebase.

Il lavoro di sviluppo si svolge so­li­ta­men­te nei co­sid­det­ti Feature-Branches (“rami di fun­zio­na­li­tà”), che vengono pe­rio­di­ca­men­te integrati nel Main-Branch (“ramo prin­ci­pa­le”). La revisione del codice viene eseguita prima del “merge”, cioè prima che il codice nuovo o mo­di­fi­ca­to venga unito al codebase esistente. L’obiettivo è quello di in­di­vi­dua­re ed eliminare i bug nelle fasi iniziali, prima che il codice venga messo in pro­du­zio­ne.

Ma l’eli­mi­na­zio­ne dei bug non è l’unico vantaggio della revisione del codice. Che il codice funzioni, cioè che venga eseguito senza errori e raggiunga il risultato de­si­de­ra­to, è solo un requisito fon­da­men­ta­le. Oltre a ciò, esistono una mol­ti­tu­di­ne di altri criteri di qualità per il codice pulito, co­no­sciu­to anche come Clean Code. La presenza di commenti, la chiarezza e la coerenza del codice, il rispetto delle linee guida di stile e l’in­te­gra­bi­li­tà nei sistemi esistenti sono tutti elementi critici che vengono presi in con­si­de­ra­zio­ne 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 ef­fet­tua­ta da altri membri del team di sviluppo e genera effetti sociali: i nuovi membri ricevono un feedback sulle con­ven­zio­ni e sulle migliori pratiche, le co­no­scen­ze vengono scambiate e di­stri­bui­te all’interno dell’or­ga­niz­za­zio­ne. In questo modo, la revisione del codice con­tri­bui­sce a pro­muo­ve­re una cultura della qualità.

Anche se ef­fet­tua­ti da persone, i processi di revisione del codice sono oggi ge­ne­ral­men­te sup­por­ta­ti da strumenti speciali. Gli strumenti di revisione del codice risultano ef­fi­cien­ti e per­met­to­no alle persone coinvolte di impiegare meno tempo nel coor­di­na­men­to dei processi. In questo modo le persone possono con­cen­trar­si sulla revisione vera e propria del codice.

Con­cet­tual­men­te, la revisione del codice da parte dell’uomo si colloca tra due metodi di analisi au­to­ma­tiz­za­ta, l’analisi statica e quella dinamica. Le dif­fe­ren­ze in sintesi:

Il concetto di revisione del codice è semplice: il codice mo­di­fi­ca­to o scritto di recente viene con­trol­la­to per ve­ri­fi­car­ne la cor­ret­tez­za da parte di uno o più membri del team di sviluppo (chiamati “revisori”). I revisori leggono il codice e iden­ti­fi­ca­no eventuali errori e va­ria­zio­ni dalle con­ven­zio­ni stabilite nel team. I revisori mi­glio­ra­no il codice con­te­stual­men­te oppure tra­smet­to­no le loro scoperte agli autori originali, che in­cor­po­ra­no le modifiche.

Per quanto l’idea sia semplice, nella pratica l’impegno ne­ces­sa­rio per i processi di revisione del codice aumenta ra­pi­da­men­te. Tuttavia, il diavolo è nei dettagli: quali modifiche vengono fatte insieme e come vengono co­mu­ni­ca­te ai revisori? In che modo gli errori e i commenti trovati vengono assegnati ai punti ap­pro­pria­ti del codice e resi di­spo­ni­bi­li ai re­spon­sa­bi­li del mi­glio­ra­men­to? Senza strumenti specifici di revisione del codice, si riescono a coor­di­na­re questi passaggi solo all’interno di team molto piccoli.

Nei team di pro­gram­ma­zio­ne di­stri­bui­ti e agili, la revisione del codice è so­li­ta­men­te parte in­te­gran­te del processo di sviluppo. Nel contesto della Con­ti­nuous In­te­gra­tion (CI), il codice viene con­ti­nua­men­te scritto, testato e mantenuto nel codebase esistente. La revisione del codice da parte di un umano fa parte della pipeline di CI au­to­ma­tiz­za­ta che ogni unità di codice at­tra­ver­sa. Solo quando tutti i test vengono superati, il codice viene integrato e suc­ces­si­va­men­te inviato ai sistemi di pro­du­zio­ne.

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. Ana­liz­za­re e for­mat­ta­re au­to­ma­ti­ca­men­te il codice nel Feature-Branch
2. Rivedere il codice e ag­giun­ge­re mi­glio­ra­men­ti
3. Unire il codice nel Main-Branch
4. Di­stri­bui­re e testare il Main-Branch sul sito di staging

3. Mettere il codice in pro­du­zio­ne

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

La revisione del codice è una parte im­por­tan­te 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’or­ga­niz­za­zio­ne. A lungo termine, questo riduce al minimo il debito tecnico; a breve termine, impedisce che il codice difettoso venga eseguito sui sistemi di pro­du­zio­ne.

Il codice è un mezzo potente; una volta scritto, lo stesso codice viene eseguito più volte o con­tem­po­ra­nea­men­te 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 cor­reg­ge­re gli errori nel codice già in ese­cu­zio­ne nel sistema di pro­du­zio­ne piuttosto che cor­reg­ger­li in anticipo.

La revisione del codice aiuta a livellare le dif­fe­ren­ze di qualità tra le diverse parti del codebase. Questo perché la qualità del codice varia no­te­vol­men­te a seconda delle cir­co­stan­ze in cui è stato scritto. I seguenti fattori abbassano la qualità dello sviluppo del codice di un pro­gram­ma­to­re o di una pro­gram­ma­tri­ce:

• mancanza di espe­rien­za di pro­gram­ma­zio­ne
• scarsa co­no­scen­za del sistema
• mancanza di fa­mi­lia­ri­tà con le con­ven­zio­ni del team
• stress durante lo sviluppo
• sviluppo sotto pressione
• esau­ri­men­to mentale

Oggi l’uso del codice va oltre la scrittura di programmi. Questo perché il codice è un mezzo espres­si­vo che si presta alla de­scri­zio­ne precisa di sistemi di ogni tipo. Ad esempio, esso viene uti­liz­za­to per rea­liz­za­re contratti in­tel­li­gen­ti basati su bloc­k­chain o per definire ambienti cloud tramite In­fra­struc­tu­re-as-Code. Anche per questi approcci si può uti­liz­za­re una revisione del codice.

Le migliori pratiche qui pre­sen­ta­te pro­ven­go­no da un ampio studio empirico condotto da Smart Bear su un team di pro­gram­ma­zio­ne Cisco. In parte, queste ri­flet­to­no i limiti dei revisori umani. Il codice è un mezzo complesso che richiede molta at­ten­zio­ne nella revisione. Gli esseri umani hanno una capacità mentale limitata che si esaurisce man mano che viene sot­to­po­sta a uno sforzo costante. Se manca l’at­ten­zio­ne, è 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 ri­scon­tra­no errori, è ne­ces­sa­rio cor­reg­ger­li. Ciò richiede re­spon­sa­bi­li­tà chiare e modalità di gestione dei processi e di mo­ni­to­rag­gio dei progressi. Diamo un’occhiata alle migliori pratiche che abbiamo trovato:

• Con­trol­la­te un massimo di 400 righe di codice per sessione: ela­bo­ran­do 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 in­di­vi­dua­re gli errori ne risente.
   
• Limitate le revisioni del codice a un massimo di 60 minuti: se si pro­trag­go­no più a lungo, i revisori perdono la con­cen­tra­zio­ne ne­ces­sa­ria.
   
• Stabilite gli obiettivi e re­gi­stra­te 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 an­no­ta­zio­ni guidano i revisori nelle modifiche al codice e le spiegano.
   
• Uti­liz­za­te liste di controllo: devono contenere gli elementi che vengono presi in con­si­de­ra­zio­ne durante ogni revisione.
   
• Stabilite un processo per cor­reg­ge­re gli errori ri­scon­tra­ti: non è suf­fi­cien­te limitarsi a rilevare gli errori. Sono ne­ces­sa­rie linee guida e strutture chiare per cor­reg­ge­re gli errori.
   
• Pro­muo­ve­te una cultura positiva della revisione del codice: gli errori non devono essere pre­sen­ta­ti come una colpa personale, ma come un’op­por­tu­ni­tà per imparare.
   
• Sfruttate le im­pli­ca­zio­ni inconsce di una revisione tra pari: se si sa che il codice è soggetto a revisione, i pro­gram­ma­to­ri si impegnano di più.
   
• Scegliete processi di revisione del codice leggeri: i moderni strumenti di revisione del codice hanno reso ef­fi­cien­te questa fase.

In generale, la revisione del codice è con­si­de­ra­ta una parte es­sen­zia­le 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 prin­ci­pa­le della revisione del codice è quello di in­di­vi­dua­re ed eliminare gli errori in anticipo, prima che causino con­se­guen­ze negative. Si tratta di un approccio molto più ef­fi­cien­te rispetto alla ri­le­va­zio­ne e cor­re­zio­ne degli errori in un momento suc­ces­si­vo del ciclo di vita del codice. Se il codice difettoso fa già parte di un sistema di pro­du­zio­ne, altri com­po­nen­ti possono basarsi su di esso, rendendo più difficili i mi­glio­ra­men­ti.

Ma i vantaggi di una regolare revisione del codice vanno oltre la ricerca di singoli errori. In par­ti­co­la­re, è im­por­tan­te con­si­de­ra­re il processo nel suo insieme: come si inserisce il codice nel codebase? Le revisioni continue del codice aiutano a iden­ti­fi­ca­re gli schemi generali e a definire gli standard. Oltre agli errori fun­zio­na­li, vengono iden­ti­fi­ca­ti e af­fron­ta­ti code smell. Se ne­ces­sa­rio, si ricorre al re­fac­to­ring e a design pattern per creare omo­ge­nei­tà tra più com­po­nen­ti.

Le revisioni del codice coin­vol­go­no i membri del team di pro­gram­ma­zio­ne e li mettono in co­mu­ni­ca­zio­ne tra loro. Perciò non sorprende che i processi con­so­li­da­ti di revisione del codice con­tri­bui­sca­no ad aumentare le com­pe­ten­ze di codifica del team. Infatti, le revisioni del codice legano e di­stri­bui­sco­no le co­no­scen­ze all’interno del team e mi­glio­ra­no le capacità di codifica dei singoli membri.

A livello or­ga­niz­za­ti­vo, le revisioni del codice aiutano a stabilire una cultura della qualità. Quando si sa che il proprio lavoro viene ri­con­trol­la­to, si tende a im­pe­gnar­si di più. Per ottenere l’effetto de­si­de­ra­to, è suf­fi­cien­te sot­to­por­re a revisione circa un terzo del codice prodotto.

Na­tu­ral­men­te, una revisione del codice comporta un maggiore sforzo per l’or­ga­niz­za­zio­ne, dato che costa tempo e impegna il personale, senza contare che sono ne­ces­sa­rie risorse per gestire i processi coinvolti. Tuttavia, i costi da sostenere servono ad aumentare la qualità del codice. Non bisogna di­men­ti­ca­re che la mancanza di qualità causa costi con­si­de­re­vo­li.

Senza strumenti di supporto per la revisione del codice, questa può risultare molto inef­fi­cien­te. Ciò era par­ti­co­lar­men­te pro­ble­ma­ti­co con i metodi tra­di­zio­na­li prima che si dif­fon­des­se 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 cal­co­la­bi­li, evitando così di rimanere in un limbo.

Per quanto riguarda gli svi­lup­pa­to­ri, le revisioni del codice do­vreb­be­ro portare a un aumento delle co­no­scen­ze e della coesione del team. A tal fine è im­por­tan­te un ambiente co­strut­ti­vo e ami­che­vo­le. Se durante una revisione del codice si ve­ri­fi­ca­no ostilità o re­cri­mi­na­zio­ni, ciò può essere trau­ma­ti­co per le persone coinvolte. I nuovi arrivati nel team, i membri di minoranze e i pro­gram­ma­to­ri e le pro­gram­ma­tri­ci re­la­ti­va­men­te inesperte ne sono par­ti­co­lar­men­te 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 è im­pos­si­bi­le da integrare nel moderno lavoro di sviluppo agile.

In contrasto con la complessa ispezione Fagan, oggi si uti­liz­za­no approcci leggeri alla revisione del codice, che coin­vol­go­no 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 al­ter­na­ti­vi. La co­mu­ni­ca­zio­ne diretta tra la persona che presenta e il revisore consente un feedback rapido e l’immediata in­cor­po­ra­zio­ne dei mi­glio­ra­men­ti.

La revisione del codice “over the shoulder” avviene in loco, sul proprio computer. Il collega o la collega guarda alle vostre spalle mentre pre­sen­ta­te il codice. Ciò consente di uti­liz­za­re tutte le risorse e gli strumenti presenti sulla macchina di sviluppo. Una revisione di questo tipo è semplice e può essere ef­fet­tua­ta ad hoc.

Con­cet­tual­men­te simile alla revisione del codice “over the shoulder” è la revisione del codice at­tra­ver­so pair pro­gram­ming. Anche in questo caso, sono coinvolti due membri del team di pro­gram­ma­zio­ne. La dif­fe­ren­za sta nella tem­pi­sti­ca dei processi di creazione e revisione del codice. Mentre la revisione del codice “over the shoulder” avviene dopo la creazione del codice, nella pro­gram­ma­zio­ne in coppia entrambi i processi sono in­trec­cia­ti.

Durante la pro­gram­ma­zio­ne in coppia, una persona, detta “driver”, scrive il codice e si occupa dei dettagli dell’im­ple­men­ta­zio­ne. 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 fun­zio­na­re da solo, ma deve anche seguire i modelli e le regole di tutti i progetti.

È im­por­tan­te che driver e reviewer si scambino re­go­lar­men­te i ruoli. In questo modo, c’è un’al­ter­nan­za di pro­spet­ti­ve, che bilancia l’equi­li­brio di potere e dà a entrambe le persone l’op­por­tu­ni­tà di re­cu­pe­ra­re men­tal­men­te. Inoltre, al par­te­ci­pan­te con meno espe­rien­za viene data la pos­si­bi­li­tà di imparare in entrambi i ruoli.

Le modifiche o l’aggiunta di nuovo codice in progetti di grandi di­men­sio­ni ri­chie­do­no 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 di­scus­sio­ne con scambio di e-mail e l’in­te­gra­zio­ne delle modifiche fino al com­ple­ta­men­to della revisione e alla fi­na­liz­za­zio­ne del codice.

Come è facile im­ma­gi­na­re, con un gran numero di col­la­bo­ra­to­ri, il processo rischia di diventare ra­pi­da­men­te confuso. Pertanto questo metodo di notifica per e-mail funziona meglio con il supporto di strumenti di revisione del codice ap­pro­pria­ti.

Gli approcci moderni alla revisione del codice uti­liz­za­no strumenti specifici per la revisione del codice. Questi strumenti strut­tu­ra­no i processi di revisione, creano ef­fi­cien­za e rac­col­go­no metriche; quindi rendono il processo di revisione pia­ni­fi­ca­bi­le, con­trol­la­bi­le e ve­ri­fi­ca­bi­le.

Esiste un’ampia gamma di strumenti per la revisione del codice. Alcuni di questi sono integrati negli approcci esistenti per la Con­ti­nuous In­te­gra­tion o la Con­ti­nuous Delivery (CI/CD). Vi pre­sen­tia­mo i diversi tipi di strumenti con alcuni esempi.

I sistemi di controllo di versione di­stri­bui­ti (“Di­stri­bu­ted version control systems”, DVCS) e in par­ti­co­la­re l’on­ni­pre­sen­te Git co­sti­tui­sco­no la base degli strumenti per la revisione del codice. Includono la fun­zio­na­li­tà di tracciare le modifiche al codice e di renderle visibili come “diff”. Le piat­ta­for­me basate su Git, come GitHub e GitLab, mi­glio­ra­no la vi­si­bi­li­tà e si con­cen­tra­no sul lavoro in team. Con le loro merge requests, queste piat­ta­for­me for­ni­sco­no una revisione del codice integrata prima di accettare nuovo codice.

Questi strumenti si basano su Git o un altro sistema di controllo di versione di­stri­bui­to (DVCS). Su questa base, per or­ga­niz­za­re le revisioni del codice all’interno del team viene so­li­ta­men­te uti­liz­za­ta un’in­ter­fac­cia utente basata sul web. Alcuni strumenti di revisione del codice hanno anche una propria in­ter­fac­cia a riga di comando (Command line interface, CLI).

GitHub si è affermato come piat­ta­for­ma standard per l’am­mi­ni­stra­zio­ne sul web dei re­po­si­to­ry Git. Il mec­ca­ni­smo prin­ci­pa­le per la revisione del codice è co­sti­tui­to dalle co­sid­det­te pull requests. Se si de­si­de­ra­no apportare modifiche al codice di un re­po­si­to­ry, si segue un semplice schema:

1. Clonare il re­po­si­to­ry come copia locale
2. Apportare modifiche al proprio branch
3. Creare una pull request: si chiede ai ma­nu­ten­to­ri del re­po­si­to­ry di rivedere le modifiche e, se sono positive, di unirle al re­po­si­to­ry prin­ci­pa­le (funzione “merge”)

Lo strumento per la revisione del codice Review Board mette in primo piano le richieste di revisione. L’in­ter­fac­cia web moderna e user-friendly fornisce un riepilogo di tutte le richieste di revisione in corso nei re­po­si­to­ry 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 in­ter­fac­cia tra le modifiche al codice e il codebase di pro­du­zio­ne. Le modifiche sono ve­ri­fi­ca­te dalla revisione del codice e vengono messe in pro­du­zio­ne solo se superano il controllo. Un’in­stal­la­zio­ne di Gerrit comprende un ambiente Git self-hosted con accesso SSH e un’in­ter­fac­cia web di­spo­ni­bi­le tramite HTTPS. Oltre alle notifiche fa­col­ta­ti­ve per e-mail, il programma include un sistema di votazione delle modifiche al codice.

Lo strumento per la revisione del codice Code Col­la­bo­ra­tor di Smart Bear mette in primo piano le storie degli utenti. Si tratta di spe­ci­fi­che di fun­zio­na­li­tà in­cen­tra­te sull’utente che vengono tradotte in codice e con­va­li­da­te at­tra­ver­so i test. Lo strumento coinvolge il team di pro­gram­ma­zio­ne, 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 uti­liz­za­ti per ana­liz­za­re e for­mat­ta­re au­to­ma­ti­ca­men­te il codice in pre­pa­ra­zio­ne alla revisione del codice. Tec­ni­ca­men­te, si tratta di un’analisi statica perché il codice viene letto ma non eseguito. I linter sono uti­liz­za­ti come parte della pipeline CI per stan­dar­diz­za­re la for­mat­ta­zio­ne del codice o per adattare il codice alle spe­ci­fi­che 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 di­gi­ta­zio­ne, iniezioni SQL ed errori out-of-bounds.

Questi strumenti, re­la­ti­va­men­te nuovi, fun­zio­na­no con­cet­tual­men­te come un editor di codice basato sul web con la sin­cro­niz­za­zio­ne delle modifiche tra più utenti. Con­sen­to­no la pro­gram­ma­zio­ne in coppia in ambienti di­stri­bui­ti e per­met­to­no revisioni del codice “over the shoulder” in­di­pen­den­te­men­te dalla propria posizione geo­gra­fi­ca. So­prat­tut­to dopo la pandemia da co­ro­na­vi­rus, questi strumenti sono diventati molto popolari.

Sia Replit, uno strumento basato sul web, che LiveShare, integrato nell’editor VSCode di Microsoft, possono essere uti­liz­za­ti come editor HTML col­la­bo­ra­ti­vi. Na­tu­ral­men­te, entrambi gli strumenti sono in grado di gestire altri linguaggi e con­sen­to­no di col­la­bo­ra­re lavorando su più file e persino di eseguire codice.