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

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.

Domande

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

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. ;)

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.

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.