È buono mantenere i commenti di bugfix all'interno del codice?

Il problema con l'aggiunta del bugfix come commento al codice è che non si ottiene la storia completa. Se vedo un pezzo di codice perfettamente scritto "questa è una soluzione 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 a bugfix nei registri di commit SCM. In questo modo, puoi vedere qual è il bug, dove è stato introdotto e come è stato risolto. Inoltre, quando arriva il momento di una versione, puoi semplicemente estrarre i registri SCM e aggiungere un punto elenco in cui è indicato un errore ed è stato corretto. Se un altro ramo o versione introduce lo stesso bug, è facile individuare la correzione e riapplicare se è effettivamente la stessa cosa.

Detto questo, sono d'accordo anche con la risposta di Charles. Se la ragione di un pezzo di codice non è ovvia, a tutti i costi, dì al manutentore che il codice è lì per un motivo, e deve essere trattato con cura.

Prevalenza. Non dirò che non dovrebbe mai essere fatto. Occasionalmente ti imbatti in qualcosa di simile a un bug in un'API esterna che devi risolvere. Il work-around 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 sé successivo non provino a "sistemare" il codice ovviamente cerebrale.

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

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

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

Circa la metà degli sviluppatori vuole che queste informazioni siano in grado di avere tutte le informazioni in un unico posto (ciò le induce a cercare le modifiche nel SCM). L'altra metà degli sviluppatori non inizia la ricerca di indizi su cosa è cambiato nel coe, ma da SCM in modo da non aver bisogno delle informazioni nel codice. Non abbiamo ancora deciso cosa fare con questi commenti. Dipende molto dal modo in cui le persone lavorano e alcune persone sono molto testarde nel lasciare i loro metodi conosciuti. Stessa cosa per commentare il blocco di codice e lasciarli nel codice per sempre.

Solo per aggiungere a ciò che Dyaster et al. hanno detto, anche se JIRA ha davvero delle belle capacità di mostrare le modifiche associate alle correzioni dei bug, la posizione migliore per documentare un bugfix è in un caso di test. Se il codice non è chiaro senza un commento che indica quale bug è stato corretto, questo è "code smell". Detto questo, se non si ha il tempo di pulire l'odore, il commento dovrebbe fare riferimento al caso di test, dove dovrebbe essere molto più ovvio perché il codice sta facendo quello che sta facendo. Se non hai il tempo di scrivere un caso di test che spiega la correzione del bug, allora il bug non è stato ancora corretto, è stato solo posticipato.

Sarei d'accordo con l'aggiunta di id di bugfix nei messaggi di commit e non all'interno del codice stesso. I bug tracker che rasentano automaticamente i messaggi di commit per i bug sono molto utili.

Inoltre, puoi utilizzare la colpa / annotate / elogia il comando del tuo sistema di controllo della versione per aiutare a 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 l'hanno modificata e l'id di commit. Dall'ID commit, puoi ottenere il messaggio completo, che dovrebbe includere l'id del bug.

I buoni sistemi VCS ti consentono di ignorare gli spazi bianchi quando calcoli chi ha modificato una linea.

Non so cosa abbia Clear Case per questa funzione.