![](\"http:\/\/alistapart.com\/it\/wp-content\/uploads\/sites\/2\/2014\/11\/sketch42112150.jpg\")
Crescendo, ho imparato che c’erano due tipi di revisioni che potevo ottenere dai miei genitori. Un genitore mi criticava usando moltissimi elogi, l’altro genitore, quello con una laurea dal Royal College of Art, mi faceva passare attraverso una critica del design. Le revisioni che cerco oggi sono per il mio codice, non per come disegno un cavallo, ma continua ad essere un processo che temo e allo stesso tempo ricerco.<\/p>\n
In questo articolo, descriver\u00f2 il mio processo, testato duramente, per condurre delle revisioni del codice, sottolineando le domande che dovreste chiedere durante il processo di revisione cos\u00ec come i necessari comandi di version control per scaricare e rivedere il lavoro di qualcuno. Supporr\u00f2 che il vostro team utilizzi Git per memorizzare il proprio codice, ma il processo funziona praticamente allo stesso modo se state usando un altro source control system.<\/p>\n
Portare a termine una peer review richiede molto tempo. Nell’ultimo progetto in cui ho introdotto le peer review obbligatorie, il senior developer ed io stimammo che avrebbe raddoppiato il tempo per completare ciascun ticket. La revisione introdusse pi\u00f9 cambiamenti di contesto per gli sviluppatori, che risultarono in una crescente frustrazione quando fu il momento di tenere aggiornati i branch attendendo la revisione del codice.<\/p>\n
I benefici, tuttavia, furono enormi. I programmatori ottennero una comprensione molto pi\u00f9 profonda dell’intero progetto mediante le loro revisioni, riducendo i silos e rendendo pi\u00f9 semplice l’aggiunta di nuove persone. I senior developer ebbero migliori opportunit\u00e0 per chiedere perch\u00e9 si stavano prendendo certe decisioni nella code base che potevano potenzialmente influenzare il lavoro futuro. E adottando un processo di peer review continuo, riducemmo la quantit\u00e0 di tempo necessaria per i test svolti dal personale per la quality assurance alla fine di ogni sprint.<\/p>\n
Analizziamo il processo. Il nostro primo passo consiste nel capire esattamente cosa stiamo cercando.<\/p>\n
La nostra revisione del codice dovrebbe sempre cominciare in un sistema per i ticket, come Jira o GitHub. Non importa se il cambiamento proposto \u00e8 una nuova feature, un bug fix, una security fix o un errore di battitura: tutti i cambiamenti dovrebbero cominciare con una descrizione del motivo per cui quella modifica \u00e8 necessaria e quale dovrebbe essere il risultato una volta che sar\u00e0 stata applicata la modifica. Questo ci permetter\u00e0 di valutare accuratamente quando il cambiamento proposto sar\u00e0 completo.<\/p>\n
Il sistema di ticketing \u00e8 dove traccerete la discussione riguardante i cambiamenti che devono essere fatti dopo aver revisionato il lavoro proposto. Dal ticketing system determinerete quale branch contiene il codice proposto. Supponiamo che il ticket che stiamo rivedendo oggi \u00e8 61524: \u00e8 stato creato per sistemare un broken link nel nostro sito web. Potrebbe allo stesso modo trattarsi di un refactoring o di una nuova feature, ma io ho scelto un bug fix come esempio. Non importa quale sia la natura del cambiamento proposto: siccome ad ogni ticket corrisponde un solo branch nel repository, sar\u00e0 pi\u00f9 semplice rivedere, e chiudere, i ticket.<\/p>\n
Configurate il vostro ambiente locale ed assicuratevi di poter riprodurre quello che attualmente \u00e8 il sito live, completo del broken link che deve essere sistemato. Quando applicate il nuovo codice localmente, dovrete catturare qualsiasi regression o problema che possa introdurre. Potete farlo solo se conoscete sicuramente la differenza tra quello che \u00e8 vecchio e quello che \u00e8 nuovo.<\/p>\n<\/div>\n
A questo punto siete pronti per buttarvi nel codice. Ipotizzer\u00f2 che stiate lavorando con i repository Git, in un setup branch-per-issue, e che il cambiamento proposto sia parte di un repository remoto del team. Lavorare direttamente dalla riga di comando \u00e8 un buon approccio universale e mi permette di creare delle istruzioni copia-incolla per i team indipendentemente dalla piattaforma.<\/p>\n
Per cominciare, aggiornate la vostra lista locale dei branch.<\/p>\n
git fetch<\/code>\n<\/pre>\nPoi elencate tutti i branch disponibili.<\/p>\n
git branch -a<\/code>\n<\/pre>\nVerr\u00e0 visualizzata una lista dei branch disponibili nella vostra finestra del terminale. Potrebbe somigliare a questa:<\/p>\n
* master\nremotes\/origin\/master\nremotes\/origin\/HEAD -> origin\/master\nremotes\/origin\/61524-broken-link<\/code>\n<\/pre>\nIl simbolo *<\/code> denota il nome del branch che state attualmente visualizzando (o da cui avete fatto “check out”). Le righe che cominciano con remotes\/origin<\/code> sono riferimento ai branch che abbiamo scaricato. Lavoreremo con una nuova copia locale del branch 61524-broken-link<\/code>.<\/p>\nQuando clonate il vostro progetto, avrete una connessione al repository remoto nel suo insieme, ma non avrete una relazione read-write con ciascuno dei singoli branch nel remote repository. Farete una connessione esplicita quando cambierete il branch. Questo significa che se avete bisogno di far girare il comando git push<\/code> per caricare i vostri cambiamenti, Git sapr\u00e0 in quale repository remoto volete pubblicare i vostri cambiamenti.<\/p>\ngit checkout --track origin\/61524-broken-link<\/code>\n<\/pre>\nTa-da! Adesso avete la vostra copia del branch per il ticket 61524, che \u00e8 connesso (“tracked”) alla copia originale nel repository remoto. Adesso potete cominciare la vostra revisione!<\/p>\n
Per prima cosa, diamo un’occhiata allo storico dei commit di questo branch con il comando log<\/code>.<\/p>\ngit log master..<\/code>\n<\/pre>\nOutput di esempio:<\/p>\n
Author: emmajane \nDate: Mon Jun 30 17:23:09 2014 -0400\n\nLink to resources page was incorrectly spelled. Fixed.\n\nResolves #61524.<\/code>\n<\/pre>\nVi fornisce l’intero messaggio di log di tutti i commit che si trovano nel branch 61524-broken-link<\/code>, ma che non si trovano anche nel branch master<\/code>. Scorrete velocemente i messaggi per farvi un’idea di quel che sta accadendo.<\/p>\nDopodich\u00e9, date una rapida occhiata al commit stesso usando il comando diff<\/code>. Questo comando mostra la differenza tra due snapshot nel vostro repository. Dovete confrontare il codice nel vostro branch checked-out con il branch con cui farete il merge, che \u00e8 convenzionalmente il branch master<\/code>.<\/p>\ngit diff master<\/code>\n<\/pre>\nCome leggere i patch files<\/h3>\n
Quando date il comando che d\u00e0 come risultato la differenza, l’informazione verr\u00e0 presentata sotto forma di un patch file. Questi ultimi sono terribili da leggere. Dovete cercare le righe che cominciano con +<\/code> o -<\/code>. Si tratta rispettivamente di righe che sono state aggiunte o rimosse. Scorrete tra i cambiamenti usando le frecce su e gi\u00f9 e premete q<\/code> per uscire quando avete finito la revisione. Se avete bisogno di un confronto ancora pi\u00f9 conciso di quello che \u00e8 successo nella patch, considerate la modifica del comando diff per elencare i file cambiati e poi osservate uno per uno i file modificati:<\/p>\ngit diff master --name-only\ngit diff master <filename><\/code>\n<\/pre>\nDiamo un’occhiata al formato di un patch file.<\/p>\n
diff --git a\/about.html b\/about.html\nindex a3aa100..a660181 100644\n\t--- a\/about.html\n\t+++ b\/about.html\n@@ -48,5 +48,5 @@\n\t(2004-05)\n\n- A full list of <a href=\"emmajane.net\/events\">public \n+ A full list of <a href=\"http:\/\/emmajane.net\/events\">public \npresentations and workshops<\/a> Emma has given is available<\/code>\n<\/pre>\nTendo ad evitare i metadati quando leggo le patch e mi concentro solo sulle righe che cominciano con -<\/code> o +<\/code>. Ci\u00f2 significa che comincio a leggere alla riga immediatamente dopo @@<\/code>. Vengono fornite alcune righe di contesto prima delle modifiche. Queste righe sono indentate ciascuna di uno spazio. Le righe di codice cambiate vengono poi mostrate con un -<\/code> (riga rimossa) o con un +<\/code> (riga aggiunta) che le precede.<\/p>\nAndare oltre la riga di comando<\/h3>\n
Usando un browser di Git repository, come gitk, vi permette di ottenere un riassunto leggermente migliore a livello visuale dell’informazione che abbiamo visto finora. La versione di Git fornita da Apple non include gitk, io ho usato Homebrew<\/a> per re-installare Git e per avere questa utility. Qualunque repository browser va bene, comunque, e ci sono molti client GUI disponibili sul sito di Git<\/a>.<\/p>\ngitk<\/code>\n<\/pre>\nQuando date il comando gitk<\/code>, si aprir\u00e0 un tool grafico dalla riga di comando. Un esempio dell’output viene dato nel seguente screenshot. Cliccate su ciascuno dei commit per averne maggiori informazioni. Molti sistemi di ticke vi permetteranno anche di vedere le modifiche in una proposta di merge “side-by-side”, quindi se lo trovate scomodo, cliccate un po’ in giro nel vostro sistema di ticketing per trovare i tool di confronto che potrebbero gi\u00e0 avere. So per certo che GitHub offre questa feature.<\/p>\n![\"Screenshot](\"http:\/\/alistapart.com\/it\/wp-content\/uploads\/sites\/2\/2014\/11\/gitk.jpg\")
<\/div>\nOra che avete osservato bene il codice, buttate gi\u00f9 le risposte alle seguenti domande:<\/p>\n
\n- Il codice \u00e8 conforme agli standard di programmazione identificati per il vostro progetto?<\/li>\n
- Il codice si limita all’ambito identificato nel ticket?<\/li>\n
- Il codice segue le best practice del settore nel modo pi\u00f9 efficiente possibile?<\/li>\n
- Il codice \u00e8 stato implementato nella maniera migliore possibile secondo le vostre specifiche interne? \u00c8 importante separare le vostre preferenze e le differenze stilistiche dai problemi reali del codice.<\/li>\n<\/ol>\n<\/div>\n\n
Applicate i cambiamenti proposti<\/h2>\n
Adesso \u00e8 il momento di avviare il vostro ambiente di test e di osservare nel contesto i cambiamenti proposti. Come sembra? La vostra soluzione \u00e8 in linea con quello che il programmatore pensa di aver realizzato? Se non sembra giusto, dovete svuotare la cache o magari ricreare l’output Sass per aggiornare il CSS del progetto?<\/p>\n
Adesso \u00e8 anche il momento di testare il codice con qualunque test suite usiate.<\/p>\n
\n- Il codice introduce qualche regression?<\/li>\n
- Il nuovo codice ha performance buone come quello vecchio? Rientra ancora nel budget di performance del vostro progetto per quel che riguarda il download time e il page rendering time?<\/li>\n
- Le parole sono tutte scritte correttamente? Seguono delle specifiche linee guida per il brand di cui siete in possesso?<\/li>\n<\/ol>\n
A seconda del contesto per questo particolare cambiamento nel codice, ci potrebbero essere altre ovvie questioni da gestire come parte della propria revisione del codice.<\/p>\n
Fate del vostro meglio per creare la lista pi\u00f9 esauriente possibile di qualunque cosa trovate sbagliata (e giusta) nel codice. \u00c8 fastidioso avere feedback da qualcuno come parte del processo di revisione, quindi cercheremo di evitare \u201cun’ultima cosa\u201d ovunque sia possibile.<\/p>\n<\/div>\n
\nPreparare il feedback<\/h2>\n
Supponiamo che ora abbiate una lunga e ricca lista di feedback. Magari non ne avrete, ma ne dubito. Se siete arrivati fin qua nell’articolo, \u00e8 perch\u00e9 vi piace esaminare attentamente il codice tanto quanto piace a me. Issate la vostra bandiera di persona strana e strutturate la vostra revisione in maniera che sia utilizzabile dai vostri colleghi.<\/p>\n
Suddividete tutti gli appunti che avete accumulato finora nelle seguenti categorie:<\/p>\n
\n- Il codice non funziona. Non compila, introduce una regression, non passa la testing suite, o in qualche modo fallisce in maniera dimostrabile. Questi sono problemi che devono assolutamente essere risolti.<\/li>\n
- Il codice non segue le best practice. Avete delle convenzioni, l’industria del web ha alcune linee guida. Questi fix sono piuttosto importanti da fare, ma possono avere delle sfumature delle quali lo sviluppatore pu\u00f2 non essere a conoscenza.<\/li>\n
- Il codice non \u00e8 come l’avreste scritto voi. Siete uno sviluppatore con delle opinioni testate in battaglia e sapete di aver ragione, semplicemente non avete ancora avuto l’occasione di aggiornare la pagina di Wikipedia per provarlo.<\/li>\n<\/ol>\n<\/div>\n\n
Inviate la vostra valutazione<\/h2>\n
Basandovi su questa nuova classificazione, siete pronti per cominciare a scrivere codice in maniera passivo-aggressiva. Se il problema \u00e8 chiaramente un errore di battitura e ricade in una delle prime due categorie, procedete con la sistemazione. Gli errori di battitura ovvi non devono per forza tornare indietro all’autore originale, giusto? Certo, il vostro collega sar\u00e0 un pochino imbarazzato, ma apprezzer\u00e0 che gli avrete fatto risparmiare un po’ di tempo e aumenterete l’efficienza del team riducendo il numero di giri che il codice deve fare tra lo sviluppatore e il revisore.<\/p>\n
Se la modifica che non vedete l’ora di fare cade nella terza categoria: stop. Non toccate il codice. Al contrario, andate dal collega e fatevi descrivere il suo approccio. Chiedere “perch\u00e9” potrebbe portarvi a delle conversazioni davvero interessanti riguardanti i merii dell’approccio intrapreso. Potrebbe anche rivelare i limite dell’approccio allo sviluppatore originale. Iniziando la conversazione, vi aprite alla possibilit\u00e0 che magari il vostro modo di fare le cose non \u00e8 l’unica soluzione possibile.<\/p>\n
Se dovete fare un qualunque cambiamento al codice, deve essere assolutamente piccolo e minore. Non dovreste fare degli edit sostanziali in un processo di peer review. Fate degli edit minori e poi aggingete i cambiamenti al vostro repository locale nel modo seguente:<\/p>\n
git add .\ngit commit -m \"[#61524] Correcting <list problem> identified in peer review.\"<\/code>\n<\/pre>\nPotete scrivere un breve messaggio dal momento che i vostri cambiamenti saranno piccoli. A questo punto dovreste fare il push del codice revisionato sul server cos\u00ec che lo sviluppatore originale possa controllarlo e revisionarlo. Supponendo che abbiate impostato il branch come tracking, si dovrebbe ridurre il tutto al comando seguente:<\/p>\n
git push<\/code>\n<\/pre>\nAggiornate la issue nel vostro sistema di ticketing in maniera appropriata per la vostra revisione. Magari il codice necessita di pi\u00f9 lavoro o andava bene cos\u00ec come era scritto ed \u00e8 ora il momento di chiudere la issue queue.<\/p>\n
Ripetete i passi in questa sezione fino a che non sar\u00e0 completo il cambiamento proposto e pronto per essere fuso con il branch principale.<\/p>\n<\/div>\n
\nFar il merge nel trunk della modifica approvata<\/h2>\n
Finora, avete confrontato il ticket branch con il master branch nel repository. Si fa riferimento a questo branch principale come al \u201ctrunk\u201d del vostro progetto. Lo step finale del processo di revisione consister\u00e0 nel fare il merge del ticket branch nel trunk e nel liberare i correspondenti ticket branch.<\/p>\n
Cominciate con l’aggiornare il vostro master branch per assicurarvi di poter pubblicare i vostri cambiamenti dopo il merge.<\/p>\n
git checkout master\ngit pull origin master<\/code>\n<\/pre>\nFate un respiro profondo e fate il merge del vostro ticket branch nel repository principale. Per come \u00e8 scritto, il seguente comando non creer\u00e0 un nuovo commit nella vostra cronologia del repositori. I commit si riposizioneranno semplicemente nel master branch, facendo git log \u2212\u2212graph<\/code> sembrer\u00e0 come se un branch separato non sia mai esistito. Se volete mantenere l’illusione di un branch passato, aggiungete semplicemente il parametro \u2212\u2212no-ff<\/code> al comando di merge, che render\u00e0 chiaro, attraverso la storia del grafo e un nuovo messaggio di commit, che avete fatto il merge di un branch a questo punto. Controllate con il vostro team quale sia l’opzione da preferite.<\/p>\ngit merge 61524-broken-link<\/code>\n<\/pre>\nIl merge pu\u00f2 o fallire o avere successo. Se non ci sono errori dal merge, siete pronti per condividere il master branch rivisto caricandolo nel repository centrale.<\/p>\n
git push<\/code>\n<\/pre>\nSe ci sono messaggi di errore dal merge, gli sviluppatori originali spesso avranno maggiori possibilit\u00e0 di capire in che modo sistemarli, quindi potreste dover chiedere a loro di risolvere i conflitti al vostro posto.<\/p>\n
Una volta che i nuovi commit sono stati integrati con successo nel branch master, potete cancellare le vecchie copie dei ticket branch sia dal vostro repository locale sia dal repository centrale. A questo punto sono semplici faccende domestiche.<\/p>\n
git branch -d 61524-broken-link\ngit push origin --delete 61524-broken-link<\/code>\n<\/pre>\n<\/div>\n\nConclusioni<\/h2>\n
Questo \u00e8 il processo che ha funzionato per i team di cui ho fatto parte. Senza un processo di peer review, pu\u00f2 essere difficile gestire i problemi in una codebase senza critiche. Con questo, il codice diventa molto pi\u00f9 collaborativo: quando si introduce un errore \u00e8 perch\u00e9 tutti e due l’abbiamo mancato. E quando si trova un errore prima che venga fatto il commit, tiriamo entrambe un sospirto di sollievo per averlo trovato quando l’abbiamo trovato.<\/p>\n
Indipendentemente se stiate usando Git o un altro source control system, il processo di peer review pu\u00f2 aiutare il vostro team. Pu\u00f2 servire pi\u00f9 tempo per sviluppare codice rivisto dai colleghi, ma contiene meno errori e ha un team forte e pi\u00f9 diversificato che lo supporta. E, s\u00ec, sono nota per aver imparato le abitudini dei miei reviewer per per aver scelto lo stile di revisione pi\u00f9 appropriato per il mio lavoro, proprio come facevo da bambina.<\/p>\n
Illustrazioni: {carlok}<\/p>\n<\/div>\n","protected":false},"excerpt":{"rendered":"
Dove si trova la revisione del codice nel vostro processo? Non fatela diventare un ripensamento n\u00e9 tanto meno evitatela completamente: Emma Jane Hogbin Westby ci mostra in questo walkthrough in che modo possiamo fare le revisioni del codice in maniera costruttiva e senza dolore. I principi qui descritti consentiranno di avere un processo di feedback oggettivo e consistente e addirittura un prodotto finale migliore, anche se non state usando Git per memorizzare il vostro codice.<\/p>\n","protected":false},"author":818,"featured_media":7000746,"comment_status":"open","ping_status":"open","template":"","categories":[119,276,278],"tags":[],"coauthors":[433],"class_list":["post-497","article","type-article","status-publish","has-post-thumbnail","hentry","category-numero-102-3-novembre-2014","category-project-management","category-workflow-tools"],"jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/alistapart.com\/it\/wp-json\/wp\/v2\/article\/497","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/alistapart.com\/it\/wp-json\/wp\/v2\/article"}],"about":[{"href":"https:\/\/alistapart.com\/it\/wp-json\/wp\/v2\/types\/article"}],"author":[{"embeddable":true,"href":"https:\/\/alistapart.com\/it\/wp-json\/wp\/v2\/users\/818"}],"replies":[{"embeddable":true,"href":"https:\/\/alistapart.com\/it\/wp-json\/wp\/v2\/comments?post=497"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/alistapart.com\/it\/wp-json\/wp\/v2\/media\/7000746"}],"wp:attachment":[{"href":"https:\/\/alistapart.com\/it\/wp-json\/wp\/v2\/media?parent=497"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/alistapart.com\/it\/wp-json\/wp\/v2\/categories?post=497"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/alistapart.com\/it\/wp-json\/wp\/v2\/tags?post=497"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/alistapart.com\/it\/wp-json\/wp\/v2\/coauthors?post=497"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}