Qual è il modo migliore per commentare in una recensione di codice?

Il mio team ha appena iniziato a utilizzare crogiolo / fisheye per iniziare le revisioni del codice ogni volta che uno di noi controlla qualcosa. Siamo solo in 3, e siamo tutti incoraggiati a rivedere il codice e lasciare commenti dove lo riteniamo opportuno.

La mia domanda è: come posso lasciare un commento su una riga di codice in cui riscontro un problema? Voglio ottenere il mio punto di vista senza sembrare abrasivo.

Non voglio sembrare come se fossi su un cavallo alto e dire " L'ho fatto in questo modo ... e inoltre non voglio sembrare che sto cercando di essere autorevole e dire qualcosa come " Questo dovrebbe essere fatto in questo modo ... " ma ho ancora bisogno di capire che quello che stanno facendo non è molto buono.

Per chiarire: questa è davvero una buona risorsa per ciò su cui dovrei cercare di commentare: una revisione del codice è soggettiva o oggettiva (quantificabile)? , ma sto cercando come commentarlo.

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 faccio notare che il codice non soddisfa i requisiti funzionali o non funziona e deve essere corretto prima di essere inviato alla produzione. Tendo ad essere molto semplice in questi commenti. I requisiti dicono ..., questo non lo fa. O questo non riuscirà se il valore inviato è nullo (specialmente quando si sa che il caso si verificherà in base ai dati che verranno inviati).

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

Poi ci sono i commenti "funziona ma facciamo le cose in questo modo". Probabilmente saranno richiesti anche questi cambiamenti. Includerebbero commenti sugli standard aziendali o sull'architettura che prevediamo vengano utilizzati. Vorrei fare riferimento allo standard o al documento di architettura e direi loro di fissare allo 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 cose simliar. Ad esempio, la nostra architettura per i pacchetti SSIS richiede che il pacchetto utilizzi il nostro database dei metadati per memorizzare informazioni particolari sul pacchetto e richiede una registrazione particolare. Il pacchetto funzionerebbe senza queste cose, ma sono necessarie per motivi aziendali (ad esempio, dobbiamo segnalare il tasso di successo delle importazioni 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 sottolinea 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 i tuoi standard di codifica, ma lo faresti in un modo diverso, devi chiederti se ciò che hanno fatto è sbagliato.

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

Potresti anche imparare qualcosa nel processo.

Voglio ottenere il mio punto di vista senza sembrare abrasivo.

Non confondere la terseness con l'essere abrasivo. Quando qualcosa è un problema, documentalo in modo che chiunque possa risolverlo possa capire. Attenersi ai fatti e non scrivere un saggio. Per dire:

• Ciò causerà un malfunzionamento del frobnitz quando il fooble si trova entro 5 grimbles del fattore snorgatz.

• La convenzione stabilita per fare ciò è chiamare fazzatz () con uno Squidge appena inizializzato. Trasformalo in un metodo in modo che accada sempre allo stesso modo e non sia duplicato.

  Inoltre, non voglio sembrare che sto cercando di essere autorevole e dire qualcosa del tipo "Questo dovrebbe essere fatto in questo modo ...", ma ho ancora bisogno di capire che quello che stanno facendo non è molto buono .

Lo scopo della revisione del codice è quello di mettere un secondo, di solito più esperto, un paio di occhi su di esso per scovare i problemi. Se sei in grado di esprimere un giudizio sul lavoro degli altri e c'è un motivo valido per dire che qualcosa non va, trascurerai la tua responsabilità di revisore se non lo facessi.

Ci saranno disaccordi, e queste sono opportunità per il revisore e il revisore di difendere le proprie posizioni. Se altrimenti sei pari e raggiungi un vicolo cieco, trova qualcuno più anziano per rompere il pareggio.

Dipende da quale tipo di problema è stato notato

• avviso mancante di copywrite - un problema comune e noioso solo un breve commento che afferma il problema e andare avanti
• luoghi in cui potrei farlo diversamente - di solito tendo a fare domande qui piuttosto che fare dichiarazioni, a volte le risposte giustificheranno la soluzione originale altre volte no e quindi posso affrontare quelle più esplicitamente
• luoghi in cui è presente un difetto evidente, ad es. sostituzione uguale che può impilare overflow - raggiungere la penna rossa - contrassegnarlo come difetto ed essere molto esplicito come motivo per cui è rotto - controllare anche altre aree simili per verificare che non si sia verificato un problema sistematico.

Dalla mia esperienza:

1. Avere sempre l'autore del codice con sé durante la revisione del suo codice. Preferibilmente il codice viene proiettato sulla lavagna ed entrambi potete vedere chiaramente il codice molto bene.

2. Avere una conversazione amichevole. Apprezzo la buona parte della codifica. Digli che "questo è il migliore che abbia mai visto" se vedi delle buone parti nel codice.

3. Chiedigli di rivedere il tuo codice e di accettare e accettare i punti validi e correggerlo. Rispetta i suoi commenti nel tuo codice e lui rispetterà automaticamente i tuoi commenti di revisione del codice.
4. Gestire a livello di sviluppatore a meno che non sia molto importante o sia necessario più tempo per correggere i problemi di revisione del codice. Non inoltrare ai gestori per semplici problemi mancanti.
5. Guarda con la prospettiva di "Imparare da un altro codice" invece di indicare errori nel codice.
6. Durante le sessioni di revisione del codice, cita gli errori passati che hai commesso e in che modo le revisioni del codice ti hanno aiutato ed evitato grandi problemi di produzione perché un altro set di occhi ti ha aiutato.
7. Sii umile. Più apprezzamento e meno commenti per lui :) Imparerai molto durante la revisione del codice e accetterà volentieri i tuoi commenti.