Le migliori pratiche di revisione del codice

L'autore beneficiando di una prospettiva diversa sul proprio compito e codice. Spesso imparano nuovi trucchi o scoprono un modo potenzialmente più ottimale di risolvere un determinato problema. Inoltre, distribuiranno il loro set di modifiche con fiducia, sapendo che altre persone hanno verificato la correttezza del codice e hanno concordato che tutto va bene.

Il recensore beneficiano del fatto di vedere in azione diversi approcci alla risoluzione dei problemi. Inoltre, miglioreranno la loro abilità nella lettura del codice, che è molto importante quando ci si immerge, ad esempio, in una libreria in fase di valutazione per l'uso in un'azienda. progetto. La revisione del codice è anche un'opportunità di apprendimento sia per il revisore che per l'autore: anche lui può imparare nuovi trucchi.

Il squadra nel suo complesso, poiché la revisione di una soluzione a un determinato problema richiede la comprensione del problema stesso almeno a un livello elevato di astrazione. Questo aiuta ad abbattere eventuali silos di conoscenza accidentali che possono verificarsi in un team. Aumenterà anche il "fattore bus": poiché almeno due persone (preferibilmente di più) sono a conoscenza di una determinata modifica, è meno probabile che si verifichi una situazione in cui nessuno del team sappia come aggiornare un modulo o perché si verifichi un determinato bug.

Il cliente beneficiano di modifiche e soluzioni distribuite in modo rapido e sicuro. Insieme ad altre best practice (come un'ottima copertura dei test, CI/CD, ambienti di staging, ecc.) le revisioni del codice assicurano anche che ciò che viene distribuito sia sicuro, sano e soddisfi i requisiti specificati.

Intento e utilizzo di queste linee guida

Ricordate che questi suggerimenti mirano soprattutto a creare un ambiente favorevole a una soluzione ambiziosa ed efficiente dei problemi, creando allo stesso tempo una rete di sicurezza e promuovendo la fiducia e la trasparenza in ogni membro del team.

Sebbene sia fortemente suggerito che un team si attenga a queste linee guida, esse non sono da intendersi come regole ferree. Questo quadro non è nemmeno inteso come un "processo" da seguire esattamente, poiché i processi rigidi tendono a ridurre la velocità e a promuovere gli sprechi.

Siete più che benvenuti a sviluppare queste linee guida all'interno del vostro team. Ricordate, tuttavia, che quando gli sviluppatori passano da un team all'altro, si aspetteranno che la revisione del codice in ogni team in cui entrano si basi ancora su questo documento. Mantenete tutte le regole aggiuntive documentate e apportate a questo documento i miglioramenti che hanno funzionato in modo eccezionale.

Responsabilità della revisione del codice

Tutti i membri del team hanno determinate responsabilità in materia di revisione del codice. Qui di seguito sono riportati alcuni dos e don't della revisione del codice, suddivisi per ruolo nel processo.

Responsabile del progetto

• FARE assicurarsi che i repository siano ben configurati (ad esempio, le fusioni al ramo di produzione non sono consentite senza almeno una revisione di approvazione).
• FARE assicuratevi che il vostro team comprenda e applichi queste pratiche e lavorate attivamente per promuovere la comprensione del perché facciamo le cose in un certo modo.
• FARE fare attenzione a eventuali situazioni di parità, in cui le opinioni opposte non possono essere risolte: in quanto leader tecnico del vostro team, è vostra responsabilità scegliere la soluzione più pertinente in questi casi e far progredire il lavoro.
• Tuttavia, NON utilizzare la leadership di progetto come strumento contundente. NON "tirare il rango". FARE Accogliete con favore la revisione e la critica delle vostre soluzioni, così come le incoraggiate sul lavoro di chiunque.
• CONSIDERATE l'aggiunta di un'integrazione GitHub al canale Slack del vostro team. Potrebbe essere utile per mettere le richieste di revisione all'attenzione dei revisori, ma a seconda del volume complessivo del vostro canale questa soluzione potrebbe essere adatta o meno al vostro team.

Membro del team

• Partecipate alle revisioni del codice. Non è accettabile non rivedere il codice.
• Ricordatevi di fare le revisioni del codice: i vostri compagni di squadra dipendono da voi per progredire nel loro lavoro!
• Se non potete assolutamente fare una determinata recensione, FARE comunicarlo in modo chiaro e aperto.
• Tuttavia, NON supporre di non poter fare una determinata revisione perché non si conosce quel modulo/l'aspetto del sistema/la logica aziendale. La revisione del codice è un'importante opportunità di apprendimento.
• Se sentite di non sapere abbastanza su qualcosa per fare una recensione, FARE chiedete all'autore: sarà lieto di spiegarvi a cosa dovrebbero servire le modifiche.
• NON negare le recensioni in base al livello di esperienza (il vostro o dell'autore).
• FARE cercate di revisionare almeno tante PR quante ne producete. L'ideale è mantenere il rapporto tra revisioni date e revisioni richieste superiore a 1 (soprattutto nei team più grandi).

Autore

• FARE capire che è vostra responsabilità far revisionare il vostro codice - il vostro team potrebbe cercare in modo proattivo le richieste di pull da revisionare, ma non è obbligato a farlo.
• NON assegnare/richiedere sempre le revisioni agli stessi membri del team: trarrete maggiori benefici da un pool di revisori variegato (e viceversa, una gamma più ampia di sviluppatori trarrà beneficio dalla revisione del vostro codice)
• NON escludere qualcuno dalla revisione in base all'esperienza. Gli sviluppatori junior traggono vantaggio dalla revisione del codice. Gli sviluppatori senior traggono beneficio dalla revisione del codice. Come indicato nella prefazione di questo documento, tutti benefici della revisione del codice.
• CONSIDERARE utilizzare un randomizzatore per selezionare i revisori. Ad esempio, in Ruby, %w[compagno di squadra1 compagno di squadra2 compagno di squadra3].sample può fare miracoli.
• FARE assegnare almeno due revisori alle richieste di pull, a meno che non sia assolutamente impossibile. In questo modo più persone beneficiano del processo (e con tre persone è più difficile arrivare a un pareggio).
• FARE siate reattivi nelle vostre richieste di pull. Anche se non dovreste interrompere il vostro flusso per rispondere immediatamente a qualsiasi commento, assicuratevi che le vostre risposte siano tempestive, altrimenti le vostre PR si attarderanno nella revisione del codice per un tempo indefinito.
• FARE avere un atteggiamento aperto. Partite sempre dal presupposto che il vostro esaminatore stia cercando di aiutarvi con tutte le migliori intenzioni. Spiegate la vostra logica, affrontate le argomentazioni del recensore e rispondete alle sue domande.
• FARE essere educati. Le incomprensioni capitano, ma non devono andare fuori controllo e danneggiare l'atmosfera del team.
• FARE essere onesti. Se credete che questa sia la soluzione migliore, ditelo e presentate le vostre argomentazioni. Se vi convincete che i suggerimenti del vostro revisore sono migliori di quelli che avete prodotto, diteglielo. Se pensate che sia possibile produrre una soluzione "migliore dei due mondi" utilizzando sia le vostre idee che quelle del vostro revisore, proponetegliela. In definitiva, lavorate per ottenere un consenso nelle vostre richieste di pull.
• FARE lasciate la risoluzione dei loro commenti al vostro revisore, non risolveteli solo perché siete convinti che ora vada bene.
• FARE spiegate attivamente il vostro compito, il vostro ragionamento e altri requisiti ai vostri revisori. Va bene non sapere, ma non è accettabile nascondere la conoscenza.
• NON supporre di sapere tutto - siamo tutti specialisti fantastici, ma è importante portare con sé una certa dose di umiltà per lavorare con voi.
• FARE essere il primo revisore del vostro codice. Indossate un cappello da revisore e scansionate il codice con attenzione, come fareste con la persona che più vi sta antipatica. Identificate ed eliminate le cose più ovvie, come le linee vuote, gli avanzi o le specifiche mancanti. Non tralasciate nulla: molto probabilmente verrà comunque evidenziato. Non fate perdere tempo ai revisori!
• FARE descrivere accuratamente la richiesta di pull. La descrizione è buona quando il revisore non sarà sorpreso da nulla durante la lettura del codice. Ricordate che non può leggere la vostra mente. Per questo motivo è importante descrivere le cose che non sono ovvie, le decisioni chiave con le relative motivazioni o tutte le nuove classi e i nuovi file.
• CONSIDERARE utilizzando il modello di richiesta di pull. Se si usa Github, aggiungerlo al proprio repository sotto la voce .github/pull_request_template.md. Incoraggia tutti i membri del team a descrivere le loro richieste di pull. È anche molto più facile scrivere quando il campo descrizione è popolato da un modello. Qui si può trovare un modello che usiamo in uno dei nostri progetti https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Autore

• FARE comprendere che è vostra responsabilità avere il vostro revisione del codice - il vostro team potrebbe cercare in modo proattivo le richieste di pull da revisionare, ma non è necessario.
• NON assegnare/richiedere sempre recensioni dallo stesso revisori di codice - trarrete maggiori benefici da un pool di revisori variegato (e viceversa, una gamma più ampia di sviluppatori trarrà beneficio dalla revisione del vostro codice)
• NON escludere qualcuno dalla revisione in base all'esperienza. I giovani sviluppatori traggono vantaggio dall'esecuzione di revisioni del codice. Gli sviluppatori senior traggono vantaggio dall'esecuzione di revisioni del codice. Come indicato nella prefazione di questo documento, tutti benefici derivanti dall'esecuzione revisioni del codice.

Recensore

• FARE utilizzare il linguaggio del suggerimento anziché quello dell'obbligo. Invece di dire "Dovresti migliorare la qualità del codice facendo invece X"., dire "Avete considerato la possibilità di migliorare qualità del codice facendo X?".
• FARE spiegare i vostri suggerimenti. "Penso che X sia meglio qui perché aiuta in trasferimento di conoscenze e migliorare la qualità del codice."
• Anche se il suggerimento proviene da fonti oggettive (ad es. stile del codice linee guida), FARE chiedere all'autore di fare qualcosa invece di dirgli di fare qualcosa. "Si prega di mantenere tutti i widget frobnicati come da nostra stile del codice guida - [link]"
• NON dare per scontato che si sappia tutto. "A me risulta che questo widget non dovrebbe mai frodare, e in queste condizioni lo farà - è un'eccezione che necessita di una revisione del codice?"
• FARE utilizzare un linguaggio inclusivo. "Credo che in futuro staremmo meglio se lo costruissimo in questo modo. Cosa ne pensate di questo migliore revisione del codice suggerimento?" e "Forse dovremmo usare X qui, invece, per una revisione efficace del codice?"
• FARE siate tempestivi nel fare il vostro revisioni del codice. Non si deve interrompere il flusso per eseguirli, ma cercare di mantenere il ciclo stretto, se possibile. Alcuni amano eseguirli all'inizio o alla fine della giornata lavorativa, come "riscaldamento" o "raffreddamento".

Si noti che queste parole chiave sono state inserite in modo da mantenere intatto il contesto e la coerenza del testo. Se desiderate inserirle in qualche punto specifico, vi preghiamo di specificarlo.