È utile conservare i commenti delle correzioni all'interno del codice?

Il mio team sta usando clear-case come controllo della versione. Il progetto a cui sto lavorando non è iniziato 7-8 anni fa. Durante l'intero ciclo di vita del progetto abbiamo avuto diverse versioni service pack correzioni di bug, ecc. I problemi vengono rilevati utilizzando il sistema di tracciamento dei bug e la maggior parte delle persone che lavorano sulle correzioni di bug segue una routine di allegare il commento in START / Blocco END con data, autore, ID bug ecc.

Ritengo che ciò sia abbastanza irrilevante e che renda il codice ingombrante e inquieto da mantenere e queste sono le cose che devono far parte dei commenti / etichette di check-in, ecc., Dove possiamo conservare ulteriori informazioni sul ciclo di vita del prodotto di lavoro.

Qual è la migliore pratica da seguire?

Alcuni dei revisori del codice insistono per pubblicare i commenti sul bug e le correzioni per facilitare la loro vita. A mio avviso, devono rivedere i file mappandoli su una vista, ottenere il registro delle modifiche del ramo e rivederlo. Sarebbe utile se potessi ottenere alcune best practice sull'invio del codice aggiornato per la revisione.

Il problema con l'aggiunta del bugfix come commento al codice è che non si ottiene la storia completa. Se vedo un codice di codice perfettamente etichettato "questa è una correzione al bug blah ", la mia prima reazione sarebbe quella di dire "e allora?". Il codice è lì, funziona. L'unica cosa che devo sapere per mantenere il codice è un commento che mi dice cosa fa.

Una pratica migliore sarebbe quella di aggiungere riferimenti ai bugfix nei log di commit di SCM. In questo modo, vedi qual è il bug, dove è stato introdotto e come è stato corretto. Inoltre, quando arriva il momento di una versione, puoi semplicemente estrarre i log di SCM e aggiungere un punto elenco che indica che c'era un bug ed è stato risolto. Se un altro ramo o versione introduce lo stesso bug, è facile individuare la correzione e riapplicare se è effettivamente la stessa cosa.

Detto questo, concordo anche con la risposta di Charles. Se il motivo di un pezzo di codice non è ovvio, in ogni caso, dire al manutentore che il codice è lì per un motivo e deve essere trattato con cura.

Principalmente cattiva pratica. Non dirò che non dovrebbe mai essere fatto. Di tanto in tanto ti imbatti in qualcosa di simile a un bug in un'API esterna che devi aggirare. La soluzione può sembrare completamente cerebrale se non si conosce il bug sottostante. In tal caso potrebbe essere una buona idea documentare il bug nel codice in modo che i colleghi o il tuo io successivo non provino a "riparare" il codice ovviamente cerebrale morto.

Cattiva pratica. I commenti diventeranno obsoleti e ingombreranno il codice. Le informazioni sono ancora disponibili nella cronologia delle versioni del sistema SCC, se necessario.

Sembra una cattiva pratica. Cosa succede se la tua organizzazione decide di migrare verso un altro sistema di tracciamento dei bug? Non legare troppo il tuo prodotto agli strumenti che stai attualmente utilizzando. Invece di fare riferimento a specifici ID bug e i motivi per cui il codice sembra simile non è chiaro, motivare la decisione di progettazione con i commenti nel codice.

La mia prima reazione sarebbe di non ripeterti, quindi tiralo fuori dal codice e dai log di SCM. Abbiamo avuto una discussione simile qui sul commento di revisione per funzioni, nomi degli autori e date di creazione di file e funzioni. In passato (prima dell'utilizzo di SCM) tutte queste informazioni venivano conservate nei file per poter ricostruire l'evoluzione di un file.

Circa la metà degli sviluppatori desidera che queste informazioni siano in grado di avere tutte le informazioni in un unico posto (questo li innesca per cercare cambiamenti nell'SCM). L'altra metà degli sviluppatori non inizia la ricerca di indizi su ciò che è cambiato in Coe, ma da SCM, quindi non ha bisogno delle informazioni nel codice. Dobbiamo ancora decidere cosa fare di questi commenti. Dipende molto dal modo in cui le persone lavorano e alcune persone sono molto testarde a lasciare i loro metodi noti. Stessa cosa per commentare il blocco di codice e lasciarli nel codice per sempre.

Solo per aggiungere a ciò che Dyaster et al. ho detto, sebbene JIRA abbia delle abilità davvero buone per visualizzare le modifiche associate alle correzioni, il posto migliore in assoluto per documentare una correzione è in un caso di prova. Se il codice non è chiaro senza un commento che indica quale bug è stato corretto, si tratta di "odore di codice". Detto questo, se non hai tempo per ripulire l'odore, il commento dovrebbe riferirsi al caso di test, dove dovrebbe essere molto più ovvio il motivo per cui il codice sta facendo quello che sta facendo. Se non hai tempo di scrivere un caso di prova che spieghi la correzione del bug, allora il bug non è stato ancora corretto, è solo stato rinviato.

Concordo con l'aggiunta di ID bugfix nei messaggi di commit e non all'interno del codice stesso. I tracker dei bug che scaricano automaticamente i messaggi di commit per gli ID dei bug sono molto utili.

Inoltre, è possibile utilizzare il comando blame / annotate / praise del sistema di controllo della versione per sostituire questi commenti. Quindi, quando esegui qualcosa del tipo:

vcs blame file.ext

puoi vedere informazioni utili, di solito incluso chi ha cambiato ogni riga, quando le ha cambiate e l'id commit. Dall'ID commit, è possibile ottenere il messaggio completo, che dovrebbe includere l'id bug.

I buoni sistemi VCS ti consentiranno di ignorare gli spazi bianchi durante il calcolo di chi ha modificato una linea.

Non so che cosa abbia Clear Case per questa funzione.