Uno sviluppatore apre una pull request che aggiunge il calcolo degli sconti a un servizio di checkout. I test vengono superati e la differenza è minima. Un revisore la approva in due minuti con un "LGTM" (LGTM - L'apprezzamento è ben accetto). Tre mesi dopo, un collega deve modificare la stessa funzione e scopre che mescola regole di prezzo, arrotondamenti e accesso al database in un unico punto. Nessuno sa dire con certezza cosa sia consentito fare.
Questo è uno scenario esemplificativo, non un incidente documentato. Mostra cosa può produrre la revisione del codice tra pari quando funziona come attività di apprendimento: un revisore in grado di individuare una modifica plausibile, identificare il problema che non è ancora un bug e spiegarlo in modo che l'autore possa intervenire.
Questa guida è destinata ai responsabili e ai manager dell'abilitazione all'ingegneria. Mostra come progettare esercizi di revisione del codice che sviluppino intenzionalmente questa competenza, invece di sperare che i revisori la acquisiscano automaticamente. Tratta il problema delle prestazioni, le lacune da diagnosticare, come strutturare la preparazione e la pratica, presenta un esempio pratico e come verificare che la competenza acquisita sia trasferibile alle revisioni reali. Prima di utilizzare la guida, è fondamentale che gli ingegneri senior convalidino ogni caso, difetto e criterio.
Che cosa sono gli esercizi di revisione del codice?
Gli esercizi di revisione del codice sono attività pratiche strutturate in cui uno sviluppatore esamina una modifica predefinita, spiega cosa ha riscontrato e perché è importante, e riceve un feedback sulla qualità della sua spiegazione. Sono diversi dalle revisioni che il tuo team esegue quotidianamente. La modifica viene scelta in anticipo, le problematiche in essa contenute sono note e l'obiettivo è migliorare le capacità di chi effettua la revisione, piuttosto che rilasciare la modifica.
I fatti in breve
| La Domanda | Risposta breve |
|---|---|
| Qual è il compito? | Spiega i risultati della revisione e fornisci un feedback che l'autore possa utilizzare. |
| Che punteggio ottieni? | Accuratezza dei risultati e utilità della spiegazione. |
| Contare i difetti è sufficiente? | No. Le recensioni riguardano molto più dei semplici difetti, quindi un esercizio che premia solo il numero di bug insegna l'abitudine sbagliata. |
| Qual è il carico cognitivo richiesto? | Analizza e valuta un progetto, quindi proponi una soluzione migliore. |
| Chi convalida il caso? | Un responsabile tecnico o un ingegnere senior che è a capo del codice sorgente. |
| Cosa non possono risolvere gli esercizi? | Tempi di revisione, proprietà poco chiara e pressione per una fusione rapida. |
| Come fai a sapere che ha funzionato? | Una nuova modifica inedita, valutata in base a criteri concordati, e un successivo follow-up sulle recensioni reali. |
1. Descrivi il problema di prestazioni
Iniziate con il compito, in una frase: data una modifica, il revisore spiega cosa ha riscontrato, perché è importante e cosa l'autore potrebbe fare al riguardo. "Spiega" è la parola chiave. Individuare un problema è metà del lavoro. Esprimerlo in modo che un collega con un punto di vista diverso possa comprenderlo, valutarlo e agire di conseguenza è l'altra metà.
La ricerca sulle moderne revisioni del codice suggerisce di guardare oltre la semplice ricerca di bug. In uno studio condotto presso Microsoft, Bacchelli e Bird hanno osservato, intervistato e sondato sviluppatori e manager. Hanno scoperto che la ricerca di difetti rimaneva la motivazione principale per le revisioni, ma che queste si concentravano meno sui difetti di quanto ci si aspettasse. Hanno inoltre riscontrato altri vantaggi, come la condivisione delle conoscenze, la consapevolezza del team e la ricerca di soluzioni alternative, e i ricercatori hanno descritto la comprensione del codice e delle modifiche come l'aspetto chiave della revisione ( Bacchelli e Bird, ICSE 2013 ). Si tratta di uno studio condotto sui team di una singola azienda, quindi è bene considerarlo come un motivo per progettare in ottica di comprensione, non come un parametro di riferimento per i propri team.
Lo standard di revisione pubblicato da Google indica la stessa direzione. Indica ai revisori di essere favorevoli all'approvazione di una modifica quando questa migliora in modo evidente la qualità complessiva del codice, anche se non è perfetta, e afferma che la revisione può insegnare qualcosa di nuovo agli sviluppatori, quindi i commenti che aiutano ad apprendere sono benvenuti ( Google Engineering Practices ). Entrambe le fonti descrivono la revisione come un momento in cui si esercita e si trasmette un giudizio. È proprio questo che i vostri esercizi dovrebbero simulare.
2. Diagnosticare le lacune di apprendimento e di contesto
Confronta il compito con le pratiche e le valutazioni del tuo attuale programma di studi.
- La pratica attuale si basa sul compito reale? Se i nuovi revisori imparano leggendo una guida di stile e poi revisionando pull request reali, si esercitano su lavori veri, senza avere la possibilità di sbagliare in un ambiente sicuro. Se la valutazione consiste in un quiz sull'etichetta delle revisioni, misura la memorizzazione delle regole, non la capacità di applicarle a una modifica.
- Qual è il carico cognitivo richiesto? Nella tassonomia di Bloom rivista, giudicare se un progetto è valido e valutarne i compromessi si colloca ai livelli di analisi e valutazione, mentre proporre una struttura migliore raggiunge il livello di creazione. Se i tuoi esercizi chiedono solo "cosa fa questo codice?", si fermano alla comprensione. La nostra guida a abbinamento delle attività di apprendimento alla tassonomia di Bloom mostra come adattare l'attività al livello.
- C'è qualcos'altro, oltre alla mancanza di abilità, che ostacola il processo? Verificate i tempi di revisione, gli strumenti, la responsabilità e le norme del team. Se i revisori hanno cinque minuti per ogni pull request, nessun esercizio produrrà una spiegazione ponderata. Se gli autori interpretano ogni commento come una critica, i revisori attenueranno le loro conclusioni fino a non dire più nulla. Segnalate queste cause a chi può risolverle.
3. Progettazione, preparazione, pratica e feedback
Assegna a ciascuna fase un compito distinto.
Preparazione. Prima di iniziare, verificate di cosa hanno bisogno i revisori: la checklist di revisione del team, i principi di progettazione su cui si basa e come leggere un diff nei vostri strumenti. Assicuratevi che il processo sia breve e a ritmo personalizzato. Una verifica di memoria conferma solo i prerequisiti e non dimostra che qualcuno sia in grado di effettuare una revisione.
Esercitati. Utilizza modifiche predefinite con un piccolo numero di problematiche di vario tipo: un bug di correttezza, un problema di manutenibilità come le responsabilità miste nell'esempio iniziale, un nome poco chiaro o un test mancante e del codice corretto. Chiedi al revisore di scrivere il commento che lascerebbe, di classificare le problematiche e di indicare quali ulteriori informazioni desidererebbe. La lezione pratica di CodeRefinery mostra come funziona: le persone aprono una pull request contenente un piccolo errore di battitura e un errore più grave, quindi la revisionano come colleghi (CodeRefinery , Practicing code review ). Crea la tua versione a partire dal tuo codice sorgente, in modo che le convenzioni e i compromessi siano reali.
Feedback. Collegalo alle decisioni prese dal revisore. "Hai notato il problema di arrotondamento, ma il tuo commento diceva 'sembra sbagliato' senza specificare quale input lo causa" è più utile di "trovati 2 su 4".
Intervento in tempo reale o revisione asincrona? L'intervento in tempo reale è più utile quando un problema è ambiguo e i revisori imparano ascoltando un ingegnere senior che spiega perché lo ha sollevato o perché lo ha ignorato. La revisione asincrona è sufficiente per confrontare i commenti con una revisione annotata da un esperto.
4. Analizza un esempio realistico
A scopo illustrativo. Un responsabile tecnico dovrebbe convalidare il caso e i criteri di risposta prima dell'utilizzo.
Il caso. Una modifica aggiunge il calcolo dello sconto a un servizio di checkout. Supera i test. In una funzione applica sconti percentuali e fissi, arrotonda il risultato, scrive nel database e invia un evento. Ha un test, per un singolo sconto percentuale.
Il compito. Il revisore scrive i commenti che vorrebbe lasciare, classifica le sue perplessità e indica cosa avrebbe bisogno di sapere prima di approvare.
Un primo tentativo. "Sembra a posto, il test è superato. Forse sarebbe meglio dividerlo?" Il revisore ha notato qualcosa, ma non ha specificato cosa, perché sia importante o cosa fare. L'autore non può intervenire.
Feedback e riprova. Il facilitatore chiede: cosa rischierebbe di compromettere una futura modifica a questa funzione? Cosa chiederesti all'autore di aggiungere prima di approvare? La richiesta di riprova richiede un commento specifico per ogni problema, con la motivazione e un suggerimento.
Un tentativo più incisivo. "La funzione applica due tipi di sconto, arrotonda, salva e pubblica un evento, quindi una modifica all'arrotondamento potrebbe alterare contemporaneamente ciò che memorizziamo e ciò che pubblichiamo. Chiederei che le regole di prezzo vengano spostate in una funzione pura che possiamo testare separatamente. L'unico test copre solo uno sconto percentuale. Chiederei uno sconto fisso e un ordine che porti il totale a zero. Non sono sicuro che l'evento debba attivarsi quando il totale è zero, quindi chiederei all'autore." Si noti che questo commento identifica il problema, ne fornisce la motivazione, formula un suggerimento concreto e dichiara ciò che il revisore non sa.
5. Valutare le capacità e pianificare il trasferimento
La prova della capacità consiste nella performance su una nuova modifica che il revisore non ha mai visto. Valuta l'accuratezza dei risultati e l'utilità della spiegazione. Una semplice griglia di valutazione utilizza una scala da 0 a 2 per ciascun criterio:
| Criterio | Prove osservabili |
|---|---|
| Esecuzione dell'attività | Individua le problematiche rilevanti legate al cambiamento e ne documenta l'esistenza. |
| Ragionamento | Spiega perché ciascuna preoccupazione è importante, offre un'alternativa e indica cosa rimane incerto. |
| Confini | Rispetta le regole di revisione del team e chiede aiuto o informazioni quando mancano l'autorità o il contesto necessari. |
Criteri di valutazione: 0 indica assenza o mancanza di supporto, 1 indica parziale con omissioni rilevanti e 2 indica completo e giustificato in base a criteri concordati. Definire separatamente gli errori critici, ad esempio l'approvazione di una modifica con rischio di perdita di dati, in modo che un buon punteggio complessivo non possa nasconderne uno. Adattare i criteri con il responsabile tecnico; questa griglia di valutazione è una proposta iniziale, non uno standard di preparazione validato. Per ulteriori informazioni sul ragionamento alla base della valutazione, consultare la nostra guida alla progettazione di esercitazioni interattive con feedback utili.
Pianifica il trasferimento. Dopo l'esercitazione, verifica un campione delle recensioni reali del revisore alcune settimane dopo, utilizzando gli stessi criteri. Confronta i risultati con un valore di riferimento rilevato prima della formazione e definisci in anticipo la popolazione e le tempistiche. Considera anche altri cambiamenti avvenuti nello stesso periodo, come l'introduzione di un nuovo strumento di revisione o un cambio di personale, prima di attribuire il merito alle esercitazioni.
6. Esegui l'esercizio in diretta o al tuo ritmo con AhaSlides.
È possibile svolgere l'esercizio in un workshop oppure lasciare che i revisori lo completino individualmente. In una sessione dal vivo, mostrate la modifica preparata e utilizzate diapositive interattive per la discussione:
- Scegli la risposta per la domanda "Quale preoccupazione solleveresti per prima?", con le preoccupazioni predefinite come opzioni. Mostra la distribuzione prima di rivelare la tua classifica.
- Aperta per "scrivi il commento che lasceresti". I recensori possono confrontare la loro formulazione con quella degli altri, ed è qui che emerge la capacità di spiegazione.
- Scala di valutazione per la domanda "quanto è grave?", in modo che il gruppo possa vedere dove i giudizi differiscono e discuterne le ragioni.
Per i revisori che non possono partecipare, la stessa sequenza può essere utilizzata in modalità autogestita, con la revisione annotata dell'esperto visualizzata dopo ogni risposta. Qualsiasi affermazione relativa all'esecuzione del codice, alle integrazioni o alle funzionalità di intelligenza artificiale deve essere considerata non confermata finché non l'avrete testata con il vostro materiale.
Se ti occupi anche di formare revisori su codice generato dall'IA, consulta la nostra guida complementare sulla formazione per la revisione di codice generato dall'IA . Quel post tratta dell'analisi dell'output generato. Questo invece spiega come le persone revisionano il lavoro altrui e come spiegano le loro osservazioni.
Vincoli che potrebbero rimanere
- È ora di rivedere. Un commento ponderato richiede più tempo di un semplice "LGTM" (LGTM - Like That), e le scadenze impongono la versione breve.
- Norme di squadra. Se il feedback viene interpretato come una critica personale, i revisori tenderanno ad ammorbidire o a ritirare le proprie valutazioni.
- Copertura del caso. Un singolo esercizio mette in luce diverse tipologie di preoccupazione. Un punteggio non descrive il giudizio di un revisore in generale.
- Trasferimento. Le prestazioni in un'officina non sono le stesse di quelle in una coda affollata, quindi controlla anche le recensioni reali.
Segnalate tempestivamente questi problemi agli sponsor e pianificate soluzioni separate. Gli esercizi migliorano la capacità di un revisore di vedere e spiegare, ma non creano i tempi o le norme necessarie.
Domande frequenti
Che cosa sono gli esercizi di revisione del codice?
Si tratta di attività pratiche predefinite in cui uno sviluppatore esamina una modifica con problematiche note, scrive i commenti che lascerebbe e riceve feedback sull'accuratezza e l'utilità. L'obiettivo è migliorare le competenze del revisore, non rilasciare la modifica.
Come si valuta se il giudizio di un revisore è migliorato?
Introducete una novità che non hanno ancora visto e valutate i risultati e la spiegazione in base a criteri concordati. Dopodiché, verificate un campione di recensioni reali alcune settimane dopo. Un quiz sulle regole di recensione serve solo a confermare i prerequisiti.
La revisione del codice tra pari serve principalmente a trovare bug?
Trovare difetti rimane una motivazione fondamentale, ma uno studio condotto da Microsoft ha rilevato che le revisioni si concentravano meno sui difetti di quanto ci si aspettasse e favorivano anche la condivisione delle conoscenze e la consapevolezza del team. Progettate esercizi che premino la capacità di spiegazione e la comprensione, oltre al conteggio dei difetti.
Dove iniziare
Scegliete un tipo di modifica che il vostro team esamina frequentemente. Scrivete la dichiarazione di prestazione, chiedete a un ingegnere senior di preparare una modifica con tre o quattro criticità predefinite e create una griglia di valutazione a tre criteri con una scala da 0 a 2 e un elenco di errori critici. Testatela con un piccolo gruppo, quindi confrontate le loro successive revisioni reali con un valore di riferimento.
Per scoprire come un esercizio di revisione può essere svolto in tempo reale con il tuo team e riutilizzato in seguito in autonomia, esplora AhaSlides.
