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 dell'abilitazione ingegneristica e ai manager dell'ingegneria. Mostra come progettare esercizi di revisione del codice che sviluppano intenzionalmente tale competenza, invece di sperare che i revisori la rilevino automaticamente. Tratta il problema delle prestazioni, le lacune da diagnosticare, come strutturare la preparazione e la pratica, un esempio pratico e come verificare che la competenza sia trasferibile alle revisioni reali. Fai convalidare ogni caso, difetto e criterio da ingegneri senior prima di utilizzarlo.
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 sulla revisione del codice moderno supporta l'idea 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 era ancora la motivazione principale per la revisione, ma che le revisioni riguardavano meno i difetti di quanto ci si aspettasse. Hanno anche fornito altri vantaggi, come la condivisione delle conoscenze, la consapevolezza del team e le soluzioni alternative, e i ricercatori hanno descritto la comprensione del codice e delle modifiche come l'aspetto chiave della revisione.Bacchelli e Bird, ICSE 2013Si tratta di uno studio sui team di una singola azienda, quindi usatelo come spunto per progettare in ottica di comprensione, non come parametro di riferimento per i vostri.
Lo standard di revisione pubblicato da Google indica la stessa direzione. Dice ai revisori di essere favorevoli all'approvazione di una modifica quando questa migliora sicuramente la salute generale del codice, anche se non è perfetta, e afferma che la revisione può insegnare qualcosa di nuovo agli sviluppatori, quindi i commenti che aiutano qualcuno ad imparare sono benvenuti.Pratiche di ingegneria di GoogleEntrambe le fonti descrivono la revisione come un luogo in cui si esercita e si trasmette un giudizio. È 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 conoscenza conferma solo i prerequisiti e non dimostra che qualcuno sia in grado di effettuare una revisione.
Pratica. Utilizza modifiche preparate con un piccolo numero di problemi iniziali di diverso 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 che va bene. Chiedi al revisore di scrivere il commento che lascerebbe, classifica i problemi e indica quali ulteriori informazioni vorrebbe. La lezione pratica di CodeRefinery mostra la struttura: le persone aprono una pull request contenente un piccolo errore di battitura e un errore più grande, quindi la revisionano come un collega (CodeRefinery, Praticare la revisione del codiceCrea il tuo codice sorgente partendo dal tuo, in modo che le convenzioni e i compromessi siano reali.
Feedback. Collega il commento 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".
Inserimento in tempo reale o revisione asincrona? L'apporto in tempo reale è particolarmente 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 al servizio di pagamento. 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 tutto a posto, il test è superato. Forse sarebbe meglio dividerlo?" Il recensore ha notato qualcosa, ma non ha specificato cosa, perché sia importante o cosa fare. L'autore non può intervenire.
Invia 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? Il tentativo successivo richiede un commento specifico su ogni problema, con la motivazione e un suggerimento.
Un tentativo più deciso. "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 essere attivato 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. |
Ancore: 0 significa assente o non supportato, 1 significa parziale con omissioni rilevanti e 2 significa 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 dell'ingegneria; questa rubrica è una proposta iniziale, non uno standard di prontezza convalidato. Per ulteriori informazioni sul ragionamento del punteggio, consultare la nostra guida a progettare attività 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 addestrate anche i revisori sul codice scritto dall'IA, consultate la nostra guida complementare su Formazione sulla revisione del codice generata dall'intelligenza artificialeQuel post riguardava la verifica dell'output generato. Questo, invece, tratta di come le persone revisionano il lavoro altrui e di come spiegano le loro scoperte.
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.
