Faccio revisioni del codice giorno per giorno da oltre un decennio ormai. I benefici delle revisioni del codice sono molti: qualcuno controlla il vostro lavoro per gli errori, si impara dalla vostra soluzione, e la collaborazione aiuta a migliorare l’approccio generale dell’organizzazione agli strumenti e all’automazione. Se attualmente non state facendo revisioni del codice nella vostra organizzazione, iniziate ora. Molte persone e organizzazioni hanno condiviso le loro migliori pratiche di revisione del codice e cosa significa per loro la definizione di buone revisioni del codice. Le guide di Google, del team SmartBear e dell’ingegnere Philipp Hauer sono tutte ottime letture. Qui sotto c’è il mio personale punto di vista su come sono le buone revisioni del codice e come renderle ancora migliori a livello di team e di organizzazione. Questo nel contesto dell’ambiente tecnologico in cui ho lavorato – attualmente a Uber, e prima ancora a Skype/Microsoft e Skyscanner. Coprono le best practice comuni e facili da seguire che ogni team può iniziare, assicurando allo stesso tempo revisioni di alta qualità e utili per il lungo termine.
Le migliori revisioni del codice sono quelle in cui gli ingegneri continuano a migliorare il modo in cui fanno le revisioni del codice. Queste revisioni del codice guardano il cambiamento del codice nel contesto della codebase, di chi lo sta richiedendo e in quale situazione. Queste revisioni adattano il loro approccio in base al contesto e alla situazione. L’obiettivo non è solo una revisione di alta qualità, ma anche quello di aiutare gli sviluppatori e i team che richiedono la revisione ad essere più produttivi.
Aree coperte dalla revisione del codice
Le buone revisioni del codice guardano il cambiamento stesso e come si inserisce nella codebase. Esaminano la chiarezza del titolo e della descrizione e il “perché” del cambiamento. Coprono la correttezza del codice, la copertura dei test, i cambiamenti di funzionalità e confermano che seguono le guide di codifica e le migliori pratiche. Faranno notare miglioramenti ovvi, come codice difficile da capire, nomi poco chiari, codice commentato, codice non testato o casi limite non gestiti. Noteranno anche quando troppi cambiamenti sono stipati in una sola revisione, e suggeriranno di mantenere i cambiamenti di codice a scopo singolo o di spezzare il cambiamento in parti più focalizzate.
Le migliori revisioni del codice guardano il cambiamento nel contesto del sistema più grande, così come controllano che i cambiamenti siano facili da mantenere. Potrebbero fare domande sulla necessità del cambiamento o su come impatta su altre parti del sistema. Guardano le astrazioni introdotte e come queste si adattano all’architettura software esistente. Prendono nota delle osservazioni di manutenibilità, come la logica complessa che potrebbe essere semplificata, migliorando la struttura dei test, rimuovendo le duplicazioni e altri possibili miglioramenti. L’ingegnere Joel Kemp descrive le grandi revisioni del codice come un passaggio contestuale che segue un iniziale, leggero passaggio.
Tono della revisione
Il tono delle revisioni del codice può influenzare notevolmente il morale all’interno dei team. Le revisioni con un tono duro contribuiscono alla sensazione di un ambiente ostile con le loro microaggressioni. Un linguaggio ostile può mettere le persone sulla difensiva, scatenando discussioni accese. Allo stesso tempo, un tono professionale e positivo può contribuire a un ambiente più inclusivo. Le persone in questi ambienti sono aperte al feedback costruttivo e le revisioni del codice possono invece innescare discussioni sane e vivaci. Offrono alternative e possibili soluzioni che potrebbero funzionare meglio per la situazione senza insistere che quelle soluzioni siano il migliore o l’unico modo di procedere. Queste revisioni assumono che il revisore potrebbe non aver capito qualcosa e chiedono chiarimenti invece di correzioni.
Le migliori revisioni del codice sono anche empatiche. Sanno che la persona che scrive il codice ha speso molto tempo e sforzo per questo cambiamento. Queste revisioni del codice sono gentili e senza pretese. Applaudono le soluzioni piacevoli e sono tutto sommato positive.
Approvare o richiedere modifiche
Una volta che un revisore completa la sua revisione, può marcarla approvata, bloccarla con richieste di modifica, o non impostare uno stato specifico, lasciandola in uno stato “non ancora approvato”. Il modo in cui i revisori usano gli stati di approvazione e di richiesta di modifiche è indicativo delle revisioni del codice.
Le buone revisioni del codice non approvano le modifiche mentre ci sono domande aperte. Tuttavia, rendono chiaro quali domande o commenti sono non bloccanti o non importanti, contrassegnandoli distintamente. Sono espliciti quando approvano un cambiamento – ad esempio aggiungendo un commento con i pollici in su come “sembra buono!”. Alcuni posti usano acronimi come LGTM – anche questi funzionano, ma siate consapevoli che i nuovi arrivati potrebbero interpretare male questi acronimi da insider per qualcos’altro. Le buone revisioni del codice sono ugualmente esplicite quando richiedono un follow-up, usando lo strumento di revisione del codice o una convenzione di squadra per comunicarlo.
Le revisioni del codice migliori sono ferme sul principio ma flessibili sulla pratica: a volte, certi commenti sono affrontati dall’autore con un cambiamento di codice separato e successivo. Per i cambiamenti che sono più urgenti di altri, i revisori cercano di rendersi disponibili per revisioni più veloci.
Dalle revisioni del codice al parlarsi l’un l’altro
Le revisioni del codice sono di solito fatte in modo asincrono e per iscritto attraverso uno strumento di revisione del codice. Questo di solito è per convenienza, per permettere revisioni di codice a distanza e per permettere a più persone di rivedere lo stesso cambiamento di codice. Ma quando è il momento di smettere di usare lo strumento – per quanto buono possa essere – e iniziare a parlare faccia a faccia del codice? Una buona revisione del codice lascia tanti commenti e domande quanti sono necessari. Se la revisione non le affronta tutte, noteranno anche quelle. Quando la conversazione diventa un lungo avanti e indietro, i revisori cercheranno di passare a parlare con l’autore di persona invece di bruciare più tempo usando lo strumento di revisione del codice.
I migliori revisori di codice raggiungeranno proattivamente la persona che fa il cambiamento dopo aver fatto un primo passaggio sul codice e avere molti commenti e domande. Queste persone hanno imparato che in questo modo risparmiano un sacco di tempo, incomprensioni e rancori. Il fatto che ci siano molti commenti sul codice indica che probabilmente c’è qualche malinteso da entrambe le parti. Questi tipi di malintesi sono più facili da identificare e risolvere parlando delle cose.
Nitpicks
Nitpicks sono commenti senza importanza, dove il codice potrebbe essere unito senza nemmeno affrontarli. Queste potrebbero essere cose come dichiarazioni di variabili in ordine alfabetico, test di unità che seguono una certa struttura, o parentesi sulla stessa linea.
Le buone revisioni del codice rendono chiaro quando le modifiche sono dei nitpick non importanti. Di solito segnano i commenti come questi in modo distinto, aggiungendo il prefisso “nit:”. Troppi di questi possono diventare frustranti e distogliere l’attenzione dalle parti più importanti della revisione, quindi i revisori mirano a non esagerare con questi.
Le revisioni di codice migliori capiscono che troppi pasticci sono un segno di mancanza di strumenti o una mancanza di standard. I revisori che si imbattono spesso in questi problemi cercheranno di risolverli al di fuori del processo di revisione del codice. Per esempio, molti dei comuni commenti nitpick possono essere risolti tramite linting automatico. Quelli che non possono essere risolti di solito dal team che si accorda su certi standard e li segue – forse anche automatizzandoli, alla fine.
Revisioni del codice per i nuovi arrivati
Iniziare in una nuova azienda è travolgente per molte persone. La base di codice è nuova, lo stile di programmazione è diverso da prima, e le persone rivedono il tuo codice in modo molto diverso. Quindi le revisioni del codice dovrebbero essere più gentili per i nuovi arrivati, per farli abituare al nuovo ambiente, o dovrebbero mantenere la barra alta come per tutti gli altri? Una buona revisione del codice usa la stessa barra di qualità e lo stesso approccio per tutti, indipendentemente dal loro titolo di lavoro, dal livello o da quando sono entrati nell’azienda. Seguendo quanto sopra, le revisioni del codice hanno un tono gentile, richiedono modifiche dove necessario, e raggiungono i revisori per parlare con loro quando hanno molti commenti.
Le revisioni del codice migliori prestano ulteriore attenzione a rendere le prime revisioni per i nuovi arrivati una grande esperienza. I revisori sono empatici con il fatto che il nuovo arrivato potrebbe non essere consapevole di tutte le linee guida di codifica e potrebbe non avere familiarità con parti del codice. Queste recensioni mettono uno sforzo aggiuntivo nello spiegare approcci alternativi e nell’indicare le guide. Sono anche molto positive nel tono, celebrando i primi cambiamenti al codice base che l’autore sta suggerendo.
Revisioni cross-uffici, cross-tempo
Le revisioni del codice diventano più difficili quando i revisori non sono nella stessa posizione. Sono particolarmente impegnative quando i revisori sono seduti in fusi orari molto diversi. Ho avuto la mia giusta quota di queste revisioni nel corso degli anni, modificando il codice di proprietà di team negli Stati Uniti e in Asia, mentre ero di base in Europa.
Le buone revisioni del codice tengono conto della differenza di fuso orario quando possono. I revisori mirano a rivedere il codice nelle ore di lavoro che si sovrappongono tra gli uffici. Per le revisioni con molti commenti, i revisori si offriranno di chattare direttamente o di fare una videochiamata per parlare dei cambiamenti.
Le migliori revisioni del codice notano quando le revisioni del codice si imbattono ripetutamente in problemi di fuso orario e cercano una soluzione sistematica, al di fuori della struttura della revisione del codice. Diciamo che un team dall’Europa sta cambiando frequentemente un servizio che fa scattare le revisioni del codice da parte del proprietario di questo servizio che ha sede negli Stati Uniti. La domanda a livello di sistema è perché questi cambiamenti avvengono così frequentemente. I cambiamenti sono fatti nella giusta codebase o dovrebbe essere cambiato un altro sistema? La frequenza dei cambiamenti sarà la stessa o diminuirà nel tempo? Supponendo che i cambiamenti siano fatti nella giusta codebase e che la frequenza non diminuisca, la dipendenza cross-office può essere rotta in qualche modo? Le soluzioni a questo tipo di problemi spesso non sono semplici e potrebbero comportare il refactoring, la creazione di nuovi servizi/interfacce o miglioramenti degli strumenti. Ma risolvere dipendenze come questa renderà la vita di entrambi i team più facile e il loro progresso più efficiente a lungo termine, il che significa che il ritorno sull’investimento è spesso abbastanza impressionante.
Supporto organizzativo
Il modo in cui le aziende e le loro organizzazioni ingegneristiche approcciano le code review è un grande elemento di quanto possano essere efficienti. Le organizzazioni che le vedono come poco importanti e banali finiscono per investire poco nel rendere le revisioni più facili. In culture come questa, si potrebbe essere tentati di eliminare del tutto le revisioni del codice. Gli ingegneri che sostengono di fare migliori revisioni del codice potrebbero sentirsi isolati, senza supporto dall’alto e alla fine si arrendono. Il risultato è un’organizzazione dove i problemi continuano a ripetersi e ad aggravarsi su se stessi.
Le organizzazioni con buone revisioni del codice assicurano che tutti gli ingegneri prendano parte al processo di revisione del codice, anche quelli che potrebbero lavorare su progetti individuali. Incoraggiano l’innalzamento dell’asticella della qualità, e i team facilitano sane discussioni sugli approcci di revisione del codice sia a livello di team che di organizzazione. Queste aziende spesso hanno guide di revisione del codice per codebase più grandi che gli ingegneri hanno iniziato e scritto. Organizzazioni come questa riconoscono che le revisioni del codice occupano una buona parte del tempo degli ingegneri. Molte di queste aziende aggiungeranno le revisioni del codice come aspettative alle competenze lavorative degli sviluppatori, aspettandosi che gli ingegneri senior spendano una grossa fetta del loro tempo a revisionare il codice degli altri.
Le organizzazioni con migliori revisioni del codice hanno regole ferree sul fatto che nessun codice entra in produzione senza una revisione del codice – proprio come le modifiche alla logica di business non entrano in produzione senza test automatici. Queste organizzazioni hanno imparato che il costo di tagliare gli angoli non vale la pena; invece, hanno processi per revisioni accelerate per i casi urgenti. Queste organizzazioni investono nella produttività degli sviluppatori, incluso il lavoro continuo per sviluppare revisioni del codice più efficienti e miglioramenti degli strumenti. I dirigenti di ingegneria utili non hanno bisogno di essere convinti dei benefici delle revisioni del codice e di altre best practice di ingegneria. Invece, sostengono iniziative su migliori strumenti o processi di revisione del codice più efficienti che provengono dai team.
Quando le persone si imbattono in revisioni che sembrano ostili, sentono di poter parlare e di avere il supporto di tutti per risolvere il problema. Gli ingegneri e i manager senior considerano le revisioni del codice che non sono all’altezza tanto quanto un codice sciatto o un comportamento povero. Sia gli ingegneri che i manager di ingegneria si sentono autorizzati a migliorare il modo in cui le revisioni del codice sono fatte.
Inizia con il buono, fallo meglio
Le buone revisioni del codice hanno già un sacco di buoni sforzi. Fanno una revisione approfondita del cambiamento stesso, evitano di essere supponenti con il tono dei commenti, e rendono chiari i pignoli. Mantengono una barra coerente, indipendentemente da chi sta richiedendo la revisione e cercano di rendere meno dolorose le revisioni tra fusi orari, prestando ulteriore attenzione a queste. Le organizzazioni che hanno buone revisioni assicurano che ogni sviluppatore riceva e faccia regolarmente revisioni del codice. Questo è già un livello alto, ma se arrivate qui, non fermatevi. Le revisioni del codice sono uno dei modi migliori per migliorare le vostre abilità, fare da mentore agli altri e imparare ad essere un comunicatore più efficiente.
Per arrivare a migliori revisioni del codice, migliorate continuamente i dettagli, ma iniziate anche a guardare i cambiamenti ad alto livello. Siate empatici nel tono dei commenti e pensate a modi al di fuori del processo di revisione del codice per eliminare i frequenti pasticci. Rendete le revisioni del codice particolarmente accoglienti per i nuovi arrivati e cercate soluzioni sistematiche per le dolorose revisioni tra fusi orari. Le organizzazioni che sono lungimiranti incoraggiano a investire in strumenti e miglioramenti dei processi per rendere le revisioni del codice migliori, raccogliendo più benefici.
—
Gergely è attualmente un engineering lead ad Amsterdam. Questo post è apparso originariamente sul blog di Gergely, The Pragmatic Engineer. Se volete leggere di più da Gergely, potete iscrivervi alla sua newsletter mensile per i suoi articoli su ingegneria, leadership tecnologica e sistemi distribuiti. Se volete contribuire con articoli al blog di Stack Overflow, inviate un’email a [email protected].
Tag: bollettino, revisione del codice, ingegneria, sviluppo software