Una recensione di codice che utilizza solo commenti di codice è una buona idea?


16

presupposti

  • Il team utilizza DVCS
  • IDE supporta l'analisi dei commenti (come TODO e così via)
  • Strumenti come CodeCollaborator sono costosi per il budget
  • Strumenti come gerrit sono troppo complessi per l'installazione o non utilizzabili

Flusso di lavoro

  • L'autore pubblica da qualche parte sul ramo delle funzionalità del repository centrale
  • Il revisore lo recupera e avvia la revisione
  • In caso di domande / revisioni, creare un commento con un'etichetta speciale, ad esempio "REV". Tale etichetta DEVE non essere nel codice di produzione - solo in fase di revisione:

    $somevar = 123;
    // REV Why do echo this here?
    echo $somevar;
    
  • Quando il revisore finisce di postare commenti, si impegna semplicemente con stupidi messaggi "commenti" e torna indietro

  • L'autore tira indietro il ramo della funzione e risponde ai commenti in modo simile o migliora il codice e lo respinge
  • Quando i commenti "REV" sono passati, possiamo pensare che la recensione sia terminata con successo.
  • L'autore ripristina in modo interattivo il ramo della funzione, lo schiaccia per rimuovere i commit di "commento" e ora è pronto a unire la funzione per sviluppare o compiere qualsiasi azione che normalmente potrebbe essere dopo una revisione interna riuscita

Supporto IDE

So che i tag di commento personalizzati sono possibili in eclipse e netbeans. Certo, dovrebbe anche essere nella famiglia blablaStorm.

Esempio di attività filtrata dai commenti personalizzata in eclipse

Domande

  1. Pensi che questa metodologia sia praticabile?
  2. Sai qualcosa di simile?
  3. Cosa può essere migliorato in esso?

Bella domanda ma non ha nulla a che fare con i tovaglioli - non è un grande titolo.
MarkJ

@MarkJ come chiamarlo allora? Intendo qualcosa di artigianale, cottage, fatto in casa. In russo abbiamo la frase "на коленке". Qualcosa di non stabile, non ideale, non solido, ma che funziona.
gaRex,

2
@MarkJ, gaRex: che dire di questo nuovo titolo? Sentiti libero di tornare se lo ritieni inappropriato per questa domanda.
Arseni Mourzenko,

@MainMa, va bene
gaRex

1
Atlassian Crucible è essenzialmente gratuito per un massimo di 10 sviluppatori. Capita anche di essere il miglior strumento di revisione del codice che ho usato. L'approccio ai commenti è praticabile ma può rendere difficile tenere traccia dello stato.
Andrew T Finnell,

Risposte:


14

L'idea è in realtà molto bella. Contrariamente ai flussi di lavoro comuni, la revisione viene mantenuta direttamente nel codice, quindi tecnicamente non è necessario altro che l'editor di testo per utilizzare questo flusso di lavoro. Anche il supporto nell'IDE è bello, in particolare la possibilità di visualizzare l'elenco delle recensioni in fondo.

Ci sono ancora alcuni svantaggi:

  • Funziona bene per team molto piccoli, ma i team più grandi richiedono il monitoraggio di ciò che è stato rivisto, quando, da chi e con quale risultato. Mentre in realtà hai questo tipo di tracciamento (il controllo della versione consente di sapere tutto ciò), è estremamente difficile da usare e cercare e spesso richiederà una ricerca manuale o semi-manuale attraverso le revisioni.

  • Non credo che il revisore abbia abbastanza feedback dal revisore per sapere come sono stati effettivamente applicati i punti recensiti .

    Immagina la seguente situazione. Alice sta rivedendo per la prima volta il codice di Eric. Nota che Eric, un giovane sviluppatore, ha usato la sintassi che non è la più descrittiva nel linguaggio di programmazione effettivamente utilizzato.

    Alice suggerisce una sintassi alternativa e invia il codice a Eric. Riscrive il codice utilizzando questa sintassi alternativa che ritiene comprensibile e rimuove il // BLAcommento corrispondente .

    La settimana successiva riceve il codice per la seconda recensione. Potrà davvero ricordare di aver fatto questa osservazione durante la sua prima recensione, per vedere come Eric l'ha risolto?

    In un processo di revisione più formale, Alice poteva immediatamente vedere che aveva fatto un'osservazione e vedere la differenza del codice pertinente, al fine di notare che Eric aveva frainteso la sintassi di cui gli aveva parlato.

  • Le persone sono ancora persone. Sono abbastanza sicuro che alcuni di questi commenti finiranno nel codice di produzione, e alcuni rimarranno come immondizia pur essendo completamente obsoleti .

    Naturalmente, lo stesso problema esiste con qualsiasi altro commento; ad esempio ci sono molti commenti TODO in produzione (incluso il più utile: "TODO: commenta il codice qui sotto"), e molti commenti che non sono stati aggiornati quando il codice corrispondente era.

    Ad esempio, l'autore originale del codice o il revisore potrebbero lasciare, e il nuovo sviluppatore non capirebbe cosa dice la recensione, quindi il commento rimarrà per sempre, in attesa che qualcuno sia troppo coraggioso per cancellarlo o per capire davvero cosa dice.

  • Ciò non sostituisce una revisione faccia a faccia (ma lo stesso problema si applica anche a qualsiasi altra revisione più formale che non viene fatta faccia a faccia).

    In particolare, se la recensione originale richiede una spiegazione, il revisore e il revisore inizieranno una sorta di discussione . Non solo ti ritroverai con grandi commenti BLA, ma quelle discussioni inquineranno anche il registro del controllo versione .

  • Potresti anche riscontrare problemi minori con la sintassi (che esiste anche per i commenti TODO). Ad esempio, cosa succede se un lungo commento "// BLA" viene generato su più righe e qualcuno decide di scriverlo in questo modo:

    // BLA This is a very long comment which is way beyond 80 characters, so it actually
    // fills more then one line. Since the next lines start with slashes, but not "BLA"
    // keyword, the IDE may not be able to show those lines, and display only the first one.
    
  • E infine come nota minore e molto personale: non scegliere "BLA" come parola chiave. Sembra brutto. ;)


"per sapere come sono stati effettivamente applicati i punti esaminati" Sì :) Solo l'onestà del recensore. Qui abbiamo più politica, che strumento.
gaRex,

1
"people are people" Sì :( Abbiamo già milioni di questi TODO. Potremmo semplicemente negare di avere una tale funzione negli IDE?
gaRex,

"inquina il registro del controllo versione" Per questo tutto il lavoro è nel ramo di funzionalità autonomo, che in seguito viene schiacciato e unito nello sviluppo. Può essere che ciò possa essere fatto con un semplice hook in DVCS. Ma come vedo tutta la complessità passa dagli strumenti di revisione del codice agli IDE e DVCS.
gaRex,

"problemi minori con la sintassi" Potrebbe non essere un problema? Quei REV sono solo alcuni marcatori per passare rapidamente dal pannello.
gaRex,

1
@gaRex: allora i membri del tuo team dovrebbero usare la posta elettronica per concordare una data di rendevouz faccia a faccia ;-)
Doc Brown,

4

Vorrei integrare i commenti nel codice con un documento di accompagnamento. Questo riassumerebbe i risultati e continuerebbe a vivere dopo che i commenti furono rimossi. I vantaggi di questo sarebbero:

  • compattezza. Se la persona non verifica regolarmente che un puntatore passato non sia nullo (o qualche altro errore comune del principiante nella lingua che stai utilizzando), il revisore può lasciare decine di commenti REV in tal senso e nel documento può dire " Ho trovato 37 posti in cui i puntatori non sono stati controllati per primi "senza elencarli tutti
  • posto per lode. Un commento come REV this is a nice designsembra strano, ma le mie recensioni di codice spesso includono l'approvazione e le correzioni
  • interattività. Il tuo commento di esempio è "perché l'hai fatto?" ed è molto tipico. Un approccio solo commenti non supporta una conversazione. La persona può modificare il proprio codice ed eliminare il commento o eliminare il commento. Ma "perché l'hai fatto?" e "per favore cambia questo, è sbagliato" non sono la stessa cosa.
  • tenere un registro. Un revisore successivo può verificare se il codice è stato effettivamente modificato o se i commenti sono stati appena rimossi. Possono anche verificare che i commenti siano stati "presi in considerazione" e che lo sviluppatore non stia più commettendo gli stessi errori in una successiva revisione.

Vorrei anche utilizzare un oggetto di lavoro per fare la recensione e rispondere alla recensione, e associare i checkin con esso. Ciò consente di trovare facilmente i commenti in un vecchio changeset e di vedere come ciascuno di essi è stato gestito in un altro changeset.


allora abbiamo bisogno di un buon strumento di revisione del codice. Il nostro attuale approccio descritto è per lo più politico poiché le persone dovrebbero inventare un po 'di etichetta e seguirlo.
gaRex,

"compattezza" - Penso che potrebbe essere fatto da un commento del tipo "// REV Dude, abbiamo 37 posti in cui i puntatori non sono stati controllati per primi, incluso questo. Per favore RTFM"
gaRex,

"posto per lode" - anche possibile, ma dopo lo schiacciamento andrà perso :( vedo già un problema - abbiamo perso la cronologia delle recensioni quando lo schiacciare commette.
gaRex

"interattività" - l'autore può rispondere in un altro commento, sotto iniziale. Proprio come in stile Wikipedia.
gaRex,

"la persona può ... eliminare il commento" - è un problema. +1
gaRex,

2

Altri hanno parlato dei limiti di questo approccio. Hai detto che strumenti come gerrit erano difficili da installare - ti suggerisco di dare un'occhiata a phabricator (http://www.phabricator.com). Questo è il sistema di revisione del codice che Facebook utilizza da anni ed è stato recentemente di provenienza aperta. Non è difficile da installare, ha flussi di lavoro eccellenti e risolve tutti i problemi menzionati negli altri commenti.


Wow! Dobbiamo provarlo invece della nostra adorabile miniera rossa.
gaRex,

"gerrit" l'ho installato - non è stato così difficile. Non riesco a usarlo! E ha anche una brutta interfaccia utente e flusso di lavoro.
gaRex,

@gaRex Usiamo Reviewboard ( reviewboard.org ) in parallelo con Redmine. Servono a scopi diversi, quindi va bene. E puoi impostare RB per collegarti ai problemi di Redmine ...
Johannes S.

@JohannesS. quale vcs stai usando? Hai anche qualche howto o wiki pronti sulla loro integrazione? Bello averne uno simile.
gaRex,

@gaRex Ci scusiamo per la risposta tardiva. Usiamo SVN, ma RB supporta anche git (in realtà, le persone RB usano git da sole). Suggerisco di dare un'occhiata al sito web di RB. È disponibile una demo online (ad esempio, controlla demo.reviewboard.org/r/101 )
Johannes S.
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.