Qual è il modo migliore per commentare una revisione del codice?

Bene, tendo a fare commenti in diverse aree generali e ogni tipo potrebbe essere gestito in modo diverso.

Modifiche richieste. Questi sono i tipi di modifiche in cui sottolineo che il codice non soddisfa i requisiti funzionali o non funziona e deve essere risolto prima di essere trasferito alla produzione. Tendo ad essere molto semplice in questi commenti. I requisiti dicono ..., questo non lo fa. O questo fallirà se il valore inviato è nullo (specialmente quando saprai che il caso si verificherà in base ai dati che verranno inviati).

Poi ci sono i "questo funziona ma qui c'è un modo migliore per realizzare quel" commento. Devi essere più gentile in questi e fare più di un passo di vendite. Potrei dire che lo farei invece perché è probabile che sia più performante (in genere riesamina il codice SQL in cui le prestazioni sono molto importanti). Potrei aggiungere alcuni dettagli sul perché è una scelta migliore, proprio come farei per rispondere a una domanda su Stack Overflow. Potrei sottolineare che non è necessario cambiarlo per questo particolare codice, ma considerare il cambiamento nella codifica futura. Fondamentalmente con questi tipi di commenti sto educando le persone con meno esperienza su cosa potrebbe funzionare meglio.

Poi ci sono i commenti "questo funziona ma facciamo le cose in questo modo". Probabilmente saranno necessari anche questi cambiamenti. Includerebbero commenti sugli standard aziendali o sull'architettura che ci aspettiamo che usino. Vorrei fare riferimento al documento standard o di architettura e dire loro di fissare lo standard. Il commento sarebbe semplice ma neutrale, manca così e così o i nomi delle variabili non sono conformi al nostro standard di denominazione o alle cose simili. Ad esempio, la nostra architettura per i pacchetti SSIS richiede che il pacchetto utilizzi il nostro database di metadati per archiviare particolari informazioni sul pacchetto e richiede una registrazione particolare. Il pacchetto funzionerebbe senza queste cose, ma sono necessarie per motivi aziendali (dobbiamo riportare il tasso di successo delle importazioni ad esempio o analizzare i tipi di errori che riceviamo).

L'unica cosa che non vuoi fare nei commenti di revisione del codice è attaccare personalmente qualcuno. Può anche aiutare se trovi qualcosa che hanno fatto bene e fai notare che era buono. A volte imparo qualcosa di nuovo da una revisione del codice e se lo facessi lo dico alla persona.

Se il codice segue gli standard di codifica, ma lo faresti in un modo diverso devi chiedertelo se ciò che hanno fatto è sbagliato.

Se non lo è ... non è come avresti fatto e non puoi lasciarlo, prova a chiedere 'Perché lo hai fatto in questo modo invece che in quel modo?' Poi li stai facendo per qualificare il motivo per cui l'hanno fatto nel modo in cui hanno fatto senza dire "l'avrei fatto in questo modo e dovresti farlo anche tu ..."

Potresti anche imparare qualcosa nel processo.

I want to get my point across without seeming abrasive.

Non confondere la chiarezza con l'essere abrasivi. Quando qualcosa è un problema, documentalo in modo che chiunque lo risolva possa capire. Attenersi ai fatti e non scrivere un tema. Con spirito:

• In questo modo il frobnitz malfunzionamento quando fooble si trova a 5 grimbles del fattore snorgatz.

• La convenzione stabilita per farlo è chiamare fazzatz () con Squidge appena inizializzato. Rendi questo in un metodo in modo che avvenga sempre allo stesso modo e non sia duplicato.

  I also don't want to seem like I'm trying to be authoritative and say something like "This should be done this way..." but I still need to get the point across that what they're doing is not very good.

Lo scopo di rivedere il codice è di mettere un secondo paio di occhi di solito più esperto su di esso per carpire i problemi. Se sei nella posizione di giudicare il lavoro altrui e c'è un valido motivo per dire che qualcosa non va bene, trascurerai la tua responsabilità di revisore se non lo facessi.

Ci saranno disaccordi, e queste sono opportunità per il revisore e il revisore per difendere le loro posizioni. Se sei pari e raggiungi un'impasse, trova qualcuno di alto livello per rompere il legame.

Dipende dal tipo di problema che è stato notato

• avviso di copywrite mancante - un problema comune e noioso solo un breve commento che indica il problema e passa a
• luoghi dove potrei farlo in modo diverso - di solito tendono a fare domande qui piuttosto che a fare dichiarazioni, a volte le risposte giustificherebbero la soluzione originale altre volte no e quindi potrei indirizzare quelle più esplicitamente
• luoghi in cui vi è un chiaro difetto, ad es. Uguale a override che può stackoverflow - raggiungere la penna rossa - contrassegnarlo come un difetto ed essere molto esplicito come il motivo per cui è rotto - anche controllare altre aree simili per verificare che non ci sia stato un problema sistematico.

Dalla mia esperienza:

1. Avere sempre l'autore del codice con te mentre rivedi il suo codice. Preferibilmente il codice è proiettato sulla lavagna e entrambi puoi vedere chiaramente il codice molto bene.

2. Avere una conversazione amichevole. Apprezzo la buona parte del     codifica. Digli che "questo è il migliore che ho visto" se ne vedi qualcuno     buone parti nel codice.

3. Chiedigli di rivedere il tuo codice e accettare e accettare il valido     punti e correggilo. Dai rispetto per i suoi commenti nel tuo codice     e darà automaticamente rispetto ai tuoi commenti di revisione del codice.
4. Gestire a livello di sviluppatore a meno che non sia molto importante o     è necessario più tempo per correggere i problemi di revisione del codice. Non aumentare a     manager per problemi semplici se mancano le condizioni.
5. Guarda invece con la prospettiva di "Imparare da un altro codice"     di indicare errori nel codice.
6. Durante le sessioni di revisione del codice, cita gli errori passati che tu     hai fatto e come le recensioni del codice ti hanno aiutato ed evitato la grande produzione     problemi perché un altro paio di occhi ti ha aiutato.
7. Sii umile. Più apprezzamento e meno commenti a lui :) Lo farai     impara molto durante la revisione del codice e anche lui accetterà volentieri il tuo     commenti.