Portare una sana mentalità di revisione del codice al tuo team

Una "revisione del codice" è un momento nel processo di sviluppo in cui tu (come sviluppatore) e i tuoi colleghi lavorate insieme e cercate i bug all'interno di un pezzo di codice recente prima che venga rilasciato. In tale momento, puoi essere l'autore del codice o uno dei revisori.

Quando esegui una revisione del codice, potresti non essere sicuro di ciò che stai cercando. D'altra parte, quando invii una revisione del codice, potresti non sapere cosa aspettare. Questa mancanza di empatia e aspettative sbagliate tra le due parti può innescare situazioni sfortunate e affrettare il processo fino a quando non finisce in un'esperienza spiacevole per entrambe le parti.

In questo articolo, condividerò come questo risultato può essere cambiato cambiando la tua mentalità durante una revisione del codice:

• Come una squadra
• Come autore
• Come recensore

Lavorare come una squadra

Promuovere una cultura della collaborazione

Prima di iniziare, è fondamentale capire il valore del perché il codice deve essere rivisto. La condivisione delle conoscenze e la coesione del team sono vantaggiose per tutti, tuttavia, se eseguita con una mentalità scadente, una revisione del codice può essere un enorme consumo di tempo con risultati spiacevoli.

L'atteggiamento e il comportamento del team dovrebbero abbracciare il valore di una collaborazione non giudicante, con l' obiettivo comune di apprendere e condividere , indipendentemente dall'esperienza di qualcun altro.

Includi le recensioni del codice nelle tue stime

Una revisione completa del codice richiede tempo. Se una modifica ha richiesto una settimana, non aspettarti che la revisione del codice richieda meno di un giorno. Semplicemente non funziona così. Non cercare di affrettare una revisione del codice né considerarla come un collo di bottiglia.

Le revisioni del codice sono importanti quanto la scrittura del codice effettivo. Come team, ricorda di includere le revisioni del codice nel flusso di lavoro e di definire le aspettative su quanto tempo potrebbe richiedere una revisione del codice, in modo che tutti siano sincronizzati e sicuri del proprio lavoro.

Risparmia tempo con le linee guida e l'automazione

Un modo efficace per garantire contributi coerenti è integrare un modello di richiesta pull nel progetto. Ciò aiuterà l'autore a presentare un PR sano con una descrizione completa. Una descrizione PR dovrebbe spiegare qual è lo scopo del cambiamento, il motivo alla base e come riprodurlo. Schermate e collegamenti di riferimento (problema Git, file di progettazione e così via) sono gli ultimi ritocchi per un invio autoesplicativo.

Fare tutto questo eviterà i primi commenti dei revisori che chiedono maggiori dettagli. Un altro modo per far sembrare le revisioni del codice meno pignolo è usare i linter per trovare problemi di formattazione e qualità del codice prima ancora che un revisore venga coinvolto. Ogni volta che vedi un commento ripetitivo durante il processo di revisione, cerca dei modi per ridurlo al minimo (essendo con linee guida migliori o automatizzazione del codice).

Resta uno studente

Chiunque può eseguire una revisione del codice e tutti devono ricevere una revisione del codice, indipendentemente dal livello di anzianità. Ricevi qualsiasi feedback con gratitudine come un'opportunità per imparare e condividere le conoscenze. Considera qualsiasi feedback come una discussione aperta piuttosto che come una reazione difensiva. Come dice Ryan Holiday:

“Un dilettante è sulla difensiva. Il professionista trova l'apprendimento (e anche, occasionalmente, essere mostrato) divertente; a loro piace essere sfidati e umiliati e si impegnano nell'istruzione come un processo continuo e senza fine. (...)”

— Ryan Holiday, L'ego è il nemico

Rimani umile perché nel momento in cui smetti di essere uno studente, la tua conoscenza diventa fragile.

L'arte di selezionare i revisori

A mio parere, scegliere i revisori è una delle decisioni più importanti per una revisione del codice efficace e sana come team.

Supponiamo che il tuo collega stia inviando una revisione del codice e decida di taggare "tutti" perché, inconsciamente, potrebbe voler accelerare il processo, fornire il miglior codice possibile o assicurarsi che tutti sappiano della modifica del codice. Ciascuno dei revisori riceve una notifica, quindi apre il collegamento PR e vede molte persone contrassegnate come revisori. Il pensiero di "qualcun altro lo farà" viene a galla nelle loro menti, portando a ignorare la revisione del codice e chiudere il collegamento.

Dal momento che nessuno ha ancora iniziato la revisione, il tuo collega ricorderà a ciascuno dei revisori di farlo, ovvero creando pressione su di loro. Una volta che i revisori iniziano a farlo, il processo di revisione richiede un'eternità perché ognuno ha la propria opinione ed è un incubo raggiungere un accordo comune. Nel frattempo, chiunque abbia deciso di non rivedere il codice, viene poi riempito di spam con miliardi di notifiche e-mail con tutti i commenti di revisione, creando così rumore nella loro produttività.

Questo è qualcosa che vedo accadere più di quanto vorrei: pull Requests con un gruppo di persone etichettate come revisori e che termina, ironia della sorte, con una revisione del codice non produttiva.

Esistono alcuni flussi comuni efficaci quando si selezionano i revisori: Un possibile flusso consiste nel selezionare da due a tre colleghi che hanno familiarità con il codice e chiedere loro di essere revisori. Un altro approccio, spiegato dal team di Gitlab, consiste nell'avere un flusso di recensioni concatenato in cui l'autore sceglie un revisore che sceglie un altro revisore finché almeno due revisori non sono d'accordo con il codice. Indipendentemente dal flusso che scegli, evita di avere troppi revisori . Essere in grado di fidarsi del giudizio del codice dei tuoi colleghi è la chiave per condurre una revisione del codice efficace e sana.

Abbi empatia

Individuare pezzi di codice da migliorare è solo una parte di una revisione del codice di successo. Altrettanto importante è comunicare quel feedback in modo sano, mostrando empatia verso i colleghi.

Prima di scrivere un commento, ricordati di metterti nei panni degli altri. È facile essere fraintesi quando si scrive, quindi rivedi le tue stesse parole prima di inviarle. Anche se una conversazione inizia a essere brutta, non lasciare che ti influenzi: sii sempre rispettoso. Parlare bene con gli altri non è mai una cattiva decisione.

Sapere come scendere a compromessi

Quando una discussione non viene risolta rapidamente, portala a una chiamata o chat personale. Analizzare insieme se è un argomento che vale la pena paralizzare l'attuale richiesta di modifica o se può essere affrontato in un altro.

Sii flessibile ma pragmatico e sa come bilanciare efficienza (consegna) ed efficacia (qualità). È un compromesso da fare in squadra. In questi momenti mi piace pensare a una revisione del codice come a un'iterazione piuttosto che a una soluzione finale. C'è sempre spazio per migliorare nel prossimo round.

Recensioni di codice di persona

Riunire l'autore e il revisore insieme in uno stile di programmazione di coppia può essere molto efficace. Personalmente, preferisco questo approccio quando la revisione del codice comporta modifiche complesse o c'è un'opportunità per una grande quantità di condivisione delle conoscenze. Nonostante si tratti di una revisione del codice offline, è buona norma lasciare commenti online sulle discussioni svolte, soprattutto quando è necessario apportare modifiche dopo la riunione. Ciò è utile anche per tenere aggiornati gli altri revisori online.

Impara dai risultati della revisione del codice

Quando una revisione del codice ha subito molte modifiche, ha richiesto troppo tempo o ha già avuto troppe discussioni, riunisci il tuo team e analizza le cause e quali azioni possono essere intraprese da esso. Quando la revisione del codice è complessa, suddividere un'attività futura in attività più piccole semplifica ogni revisione del codice.

Quando il divario di esperienza è grande, l'adozione della programmazione di coppia è una strategia con risultati incredibili, non solo per la condivisione delle conoscenze ma anche per la collaborazione e la comunicazione offline. Qualunque sia il risultato, punta sempre a una squadra sana e dinamica con aspettative chiare.

Come autore

Una delle preoccupazioni principali quando si lavora su una revisione del codice come autore è ridurre al minimo la sorpresa del revisore quando legge il codice per la prima volta. Questo è il primo passo per una revisione del codice prevedibile e regolare. Ecco come puoi farlo.

Stabilire una comunicazione precoce

Non è mai una cattiva idea parlare con i tuoi futuri revisori prima di scrivere troppo codice. Ogni volta che si tratta di un contributo interno o esterno, potresti fare un perfezionamento insieme o un po' di programmazione in coppia all'inizio dello sviluppo per discutere le soluzioni.

Non c'è niente di sbagliato nel chiedere aiuto come primo passo. Infatti, lavorare insieme al di fuori della revisione è un primo passo importante per prevenire errori precoci e garantire un primo accordo. Allo stesso tempo, i revisori vengono a conoscenza di una futura revisione del codice da effettuare.

Segui le linee guida

Quando invii una Pull Request per essere rivisto, ricordati di aggiungere una descrizione e di seguire le linee guida. Ciò eviterà ai revisori di dedicare tempo alla comprensione del contesto del nuovo codice. Anche se i tuoi revisori sanno già di cosa si tratta, puoi anche cogliere questa opportunità come un modo per migliorare le tue capacità di scrittura e comunicazione.

Sii il tuo primo recensore

Vedere il tuo codice in un contesto diverso ti consente di trovare cose che ti mancherebbero nel tuo editor di codice. Esegui una revisione del codice del tuo codice prima di chiedere ai tuoi colleghi. Avere una mentalità da recensore e passare davvero attraverso ogni riga di codice.

Personalmente, mi piace annotare le mie recensioni di codice per guidare meglio i miei revisori. L'obiettivo qui è prevenire commenti relativi a una possibile mancanza di attenzione e assicurarsi di aver seguito le linee guida del contributo. Cerca di inviare una recensione del codice proprio come vorresti riceverne una.

Essere pazientare

Dopo aver inviato una recensione del codice, non saltare direttamente in un nuovo messaggio privato chiedendo ai tuoi revisori di "dare un'occhiata, ci vogliono solo pochi minuti" e indirettamente bramando quell'emoji con il pollice in su. Cercare di affrettare i tuoi colleghi a fare il loro lavoro non è una mentalità sana. Invece, fidati del flusso di lavoro dei tuoi colleghi poiché si fidano di te per inviare una buona revisione del codice. Nel frattempo, aspetta che ti rispondano quando sono disponibili. Non considerare i tuoi revisori come un collo di bottiglia. Ricorda di essere paziente perché le cose difficili richiedono tempo.

Sii un ascoltatore

Una volta inviata una revisione del codice, arriveranno commenti, verranno poste domande e verranno proposte modifiche. La regola d'oro qui è di non prendere alcun feedback come un attacco personale. Ricorda che qualsiasi codice può trarre vantaggio da una prospettiva esterna .

Non guardare i tuoi revisori come un nemico. Invece, prendi questo momento per mettere da parte il tuo ego, accetta di commettere errori e sii aperto a imparare dai tuoi colleghi, in modo da poter fare un lavoro migliore la prossima volta.

Come revisore

Pianifica in anticipo sui tempi

Quando ti viene chiesto di essere un revisore, non interrompere le cose subito. È un errore comune che vedo sempre. La revisione del codice richiede la tua piena attenzione e ogni volta che cambi contesto del codice, stai diminuendo la tua produttività perdendo tempo a ricalibrare la tua attenzione. Invece, pianifica in anticipo assegnando le fasce orarie della tua giornata per fare revisioni del codice.

Personalmente, preferisco fare le revisioni del codice come prima cosa al mattino o dopo pranzo prima di scegliere qualsiasi altro dei miei compiti. Questo è ciò che funziona meglio per me perché il mio cervello è ancora fresco senza un contesto di codice precedente da cui staccare. Oltre a ciò, una volta terminata la recensione, posso concentrarmi sui miei compiti, mentre l'autore può rivalutare il codice in base al feedback.

Sii solidale

Quando una Pull Request non segue le linee guida sui contributi, sii solidale, specialmente con i nuovi arrivati. Cogli questo momento come un'opportunità per guidare l'autore a migliorare il suo contributo. Nel frattempo, cerca di capire perché l'autore non ha seguito le linee guida in primo luogo. Forse c'è spazio per miglioramenti di cui prima non eri a conoscenza.

Dai un'occhiata al ramo ed eseguilo

Durante la revisione del codice, fallo funzionare sul tuo computer, specialmente quando si tratta di interfacce utente. Questa abitudine ti aiuterà a comprendere meglio il nuovo codice e individuare le cose che potresti perdere se hai appena utilizzato uno strumento diff predefinito nel browser che limita l'ambito della revisione al codice modificato (senza avere il contesto completo come nell'editor di codice) .

Chiedi prima di assumere

Quando non capisci qualcosa, non aver paura di dirlo e di fare domande. Quando chiedi, ricorda di leggere prima il codice circostante ed evitare di fare supposizioni.

La maggior parte delle domande rientra in questi due tipi di categorie:

1. Domande sul "come".
   Quando non capisci come funziona o cosa fa qualcosa, valuta con l'autore se il codice è sufficientemente chiaro. Non confondere il codice semplice con l'ignoranza. C'è una differenza tra codice difficile da leggere e codice di cui non sei a conoscenza. Sii aperto all'apprendimento e all'uso di una nuova funzionalità linguistica, anche se non la conosci ancora a fondo. Tuttavia, usalo solo se semplifica la codebase.
2. Domande "perché".
   Quando non capisci il "perché", non aver paura di suggerire di commentare il codice, soprattutto se si tratta di un caso limite o di una correzione di bug. Il codice dovrebbe essere autoesplicativo quando si tratta di spiegare cosa fa. I commenti sono un complemento per spiegare il perché dietro un certo approccio. Spiegare il contesto è molto prezioso quando si tratta di manutenibilità e salverà qualcuno dall'eliminazione di un blocco di codice che pensava fosse inutile. (Personalmente, mi piace commentare il codice finché non mi sento sicuro di dimenticarlo in seguito.)

Critica costruttiva

Una volta trovato un pezzo di codice che ritieni debba essere migliorato, ricordati sempre di riconoscere lo sforzo dell'autore nel contribuire al progetto ed esprimerti in modo ricettivo e trasparente.

• Discussioni aperte.
  Evita di formalizzare il tuo feedback come un comando o un'accusa come "Dovresti..." o "Hai dimenticato...". Esprimi il tuo feedback come una discussione aperta invece che come una richiesta obbligatoria. Ricordati di commentare il codice, non l'autore. Se il commento non riguarda il codice, non dovrebbe appartenere a una revisione del codice. Come detto prima, sii solidale. Usare una voce passiva, parlare al plurale, esprimere domande o suggerimenti sono buoni approcci per enfatizzare l'empatia con l'autore.
  

Invece di "Estrai questo metodo da qui...", preferisci "Questo metodo dovrebbe essere estratto..." o "Cosa ne pensi di estrarre questo metodo..."

• Essere chiaro.
  Un feedback può essere facilmente interpretato erroneamente, soprattutto quando si tratta di esprimere un'opinione anziché condividere un fatto o una linea guida. Ricorda sempre di cancellarlo subito nel tuo commento.

Non chiaro: "Questo codice dovrebbe essere..."

Opinione: "Credo che questo codice dovrebbe essere..."

Fatto: "Seguendo [le nostre linee guida], questo codice dovrebbe essere...".

• Spiega perchè.
  Ciò che è ovvio per te, potrebbe non esserlo per gli altri. Non spiega mai troppo la motivazione alla base del tuo feedback, quindi l'autore non solo capisce come cambiare qualcosa, ma anche qual è il vantaggio che ne deriva.

Opinione: “Credo che questo codice possa essere…”

Spiegazione: "Credo che questo codice potrebbe essere (...) perché ciò migliorerà la leggibilità e semplificherà gli unit test".

• Fornisci esempi.
  Quando condividi una caratteristica del codice o uno schema con cui l'autore non ha familiarità, completa il tuo suggerimento con un riferimento come guida. Quando possibile, vai oltre i documenti MDN e condividi uno snippet o un esempio funzionante adattato allo scenario di codice corrente. Quando scrivere un esempio è troppo complesso, sii solidale e offriti di aiutare di persona o tramite una videochiamata.

Oltre a dire qualcosa come "L'uso del filtro ci aiuterà a [motivare]", dì anche: "In questo caso, potrebbe essere qualcosa del tipo: [frammento di codice]. Puoi controllare [un esempio su Finder.js]. Qualsiasi dubbio, sentiti libero di inviarmi un ping su Slack.

• Essere ragionevole.
  Se lo stesso errore viene commesso più volte, preferisci lasciare un solo commento a riguardo e ricorda che l'autore lo riveda anche negli altri posti. L'aggiunta di commenti ridondanti crea solo rumore e potrebbe essere controproducente.

Mantieni il focus

Evita di proporre modifiche al codice non correlate al codice corrente. Prima di suggerire un cambiamento, chiediti se è strettamente necessario in quel momento. Questo tipo di feedback è particolarmente comune nei refactors. È uno dei tanti compromessi tra efficienza ed efficacia che dobbiamo fare come squadra.

Quando si parla di refactoring, personalmente, tendo a preferire piccoli ma efficaci miglioramenti . Questi sono più facili da rivedere e ci sono meno possibilità di avere conflitti di codice quando si aggiorna il ramo con il ramo di destinazione.

Imposta le aspettative

Se lasci una revisione del codice a metà, informa l'autore, in modo che le aspettative di tempo siano sotto controllo. Alla fine, fai anche sapere all'autore se sei d'accordo con il nuovo codice o se desideri rivederlo nuovamente in seguito.

Prima di approvare una revisione del codice, chiediti se sei a tuo agio sulla possibilità di toccare quel codice in futuro. Se sì, è un segno che hai eseguito con successo una revisione del codice!

Impara a rifiutare una revisione del codice

Anche se nessuno lo ammette, a volte devi rifiutare una revisione del codice. Nel momento in cui decidi di accettare una revisione del codice ma provi ad affrettarla, la qualità del progetto viene compromessa così come la mentalità del tuo team.

Quando accetti di rivedere il codice di qualcun altro, quella persona si fida delle tue capacità: è un impegno. Se non hai il tempo per essere un revisore, dì semplicemente di no ai tuoi colleghi. Dico davvero; non lasciare che i tuoi colleghi aspettino una revisione del codice che non verrà mai eseguita. Ricordarsi di comunicare e mantenere chiare le aspettative . Sii onesto con il tuo team e, ancora meglio, con te stesso. Qualunque sia la tua scelta, fallo in modo sano e fallo nel modo giusto.

Conclusione

Con abbastanza tempo ed esperienza, fare revisioni del codice ti insegnerà molto di più della semplice conoscenza tecnica. Imparerai a dare e ricevere feedback dagli altri, oltre a prendere decisioni con più attenzione.

Ogni revisione del codice è un'opportunità per crescere come comunità e individualmente. Anche al di fuori delle revisioni del codice, ricorda di promuovere una mentalità sana fino al giorno in cui verrà naturale per te e i tuoi colleghi. Perché la condivisione è ciò che ci rende migliori!

Ulteriori letture su SmashingMag:

• Lavorare insieme: come designer e sviluppatori possono comunicare per creare progetti migliori
• Migliore collaborazione coinvolgendo i progettisti nel processo di revisione del codice
• Quali podcast dovrebbero ascoltare web designer e sviluppatori?
• Come creare il curriculum perfetto per sviluppatori Web