Usi commenti speciali sulle correzioni dei bug nel tuo codice?


16

Alcuni dei miei colleghi utilizzare i commenti particolari sulle loro correzioni di bug, per esempio:

// 2008-09-23 John Doe - bug 12345 
// <short description> 

Ha senso?
Commenta le correzioni di bug in un modo speciale?

Per favore fatemi sapere.

33

Non inserisco commenti del genere, il sistema di controllo del codice sorgente mantiene già quella cronologia e sono già in grado di registrare la cronologia di un file.

Inserisco commenti che descrivono perché viene fatto qualcosa di non ovvio. Quindi se la correzione del bug rende il codice meno prevedibile e chiaro, allora spiego perché.


4

Solo se la soluzione era particolarmente intelligente o difficile da capire.


3

Commenti come questo sono il motivo per cui Subversion consente di digitare una voce di registro su ogni commit. Ecco dove dovresti mettere questa roba, non nel codice.


15

Nel corso del tempo questi possono accumularsi e aggiungere confusione. È meglio rendere chiaro il codice, aggiungere commenti per trucchi correlati che potrebbero non essere ovvi e mantenere i dettagli del bug nel sistema di tracciamento e nel repository.

  0

Hai completamente ragione. Ricordo un metodo nel nostro codice, che sembra consistere solo di correzioni di bug (per quanto riguarda il tipo di commenti sopra menzionati)! 23 set. 082008-09-23 21:23:31

  0

Che cos'è un repository del sistema di tracciamento? 27 set. 112011-09-27 16:15:32

  0

Quando ho menzionato "sistema di tracciamento e repository" mi riferivo a due cose. Uno, un sistema di tracciamento dei bug, come bugzilla o JIRA in cui è possibile inserire commenti su un problema. In secondo luogo, un repository di codice sorgente come SVN o Git in cui è possibile inserire commenti con commit. 29 set. 112011-09-29 19:40:22


2

Mentre io tendo a vedere alcuni commenti sui bug all'interno del codice al lavoro, la mia preferenza personale è collegare un commit di codice a un bug. Quando dico uno intendo davvero un insetto. In seguito puoi sempre controllare le modifiche apportate e sapere a quali bug sono state applicate.


0

Per individuare quelli commento specifico usiamo DKBUGBUG - il che significa fix e recensore di David Kelley può facilmente identità, Naturalmente l'aggiungeremo Data e altro numero di tracking di bug VSTS ecc insieme a questo.


6

Tendo a non commentare nella sorgente reale perché può essere difficile tenersi aggiornati. Tuttavia, inserisco commenti di collegamento nel mio registro di controllo sorgente e nel tracciamento dei problemi. per esempio. Potrei fare qualcosa di simile in Perforce:

[Bug-Id] Problema con la finestra di dialogo xyz. Spostamento del codice di dimensionamento in abc e ora inizializzato in seguito.

Poi nel mio issue tracker farò qualcosa di simile:

fisso in elenco modifiche 1234.

Spostato dimensionamento codice per ABC e ora inizializzazione in seguito.

Perché allora viene lasciato un buon indicatore storico. Inoltre, rende facile sapere perché una determinata riga di codice è in un certo modo, basta guardare la cronologia dei file. Una volta trovata la riga di codice, puoi leggere il mio commento di commit e vedere chiaramente quale errore era e come l'ho risolto.


4

Di solito aggiungo il mio nome, il mio indirizzo e-mail e la data insieme a una breve descrizione di ciò che ho cambiato, perché in quanto consulente fisso spesso il codice di altre persone.

// Glenn F. Henriksen (<[email protected]) - 2008-09-23 
// <Short description> 

In questo modo i responsabili dei codici, o le persone provenienti in dopo di me, riesco a capire cosa è successo e che possono entrare in contatto con me se devono.

(sì, purtroppo, il più delle volte non hanno il controllo di origine ... per le cose io uso interno di monitoraggio TFS)

+2

Sourcecontrol tiene traccia di tutte queste informazioni. E, poiché sei un consulente, dovresti consultare il tuo cliente per utilizzare un sistema di controllo del codice sorgente. 02 feb. 112011-02-02 08:13:01

+1

Mi consulto, ma a volte il mio consiglio cade nel vuoto. Se il client ha il controllo del codice sorgente, non inserisco mai questi commenti, quindi è solo un rumore extra. 05 apr. 112011-04-05 19:46:22

  0

Qual è il sistema di controllo del codice sorgente? 27 set. 112011-09-27 16:16:40

  0

@MarkKramer Dipende dal client. Microsoft Team Foundation è la più comune. Anche Git è usato un po '. Ogni tanto mi imbatto in Visual SourceSafe ... 10 ott. 112011-10-10 13:16:19


1

No non lo faccio, e io odio dover graffiti come quella lettiera il codice. I numeri dei bug possono essere rintracciati nel messaggio di commit al sistema di controllo della versione e tramite script per inviare messaggi di commit rilevanti nel sistema di tracciamento dei bug. Non credo che appartengano al codice sorgente, dove le future modifiche confonderanno semplicemente le cose.


4

Mentre questa può sembrare una buona idea in quel momento, diventa rapidamente fuori controllo. Tali informazioni possono essere meglio catturate usando una buona combinazione di sistema di controllo del codice sorgente e bug tracker. Naturalmente, se c'è qualcosa di complicato in corso, un commento che descrive la situazione sarebbe utile in ogni caso, ma non la data, il nome o il numero di bug.

La base di codice su cui sto lavorando al lavoro ha qualcosa come 20 anni e sembra che abbia aggiunto molti commenti come questo anni fa. Fortunatamente, hanno smesso di farlo alcuni anni dopo aver convertito tutto in CVS alla fine degli anni '90. Tuttavia, tali commenti sono ancora disseminati nel codice e la politica ora è "rimuoverli se stai lavorando direttamente su quel codice, ma altrimenti lasciali". Sono spesso molto difficili da seguire, specialmente se lo stesso codice viene aggiunto e rimosso più volte (sì, succede). Inoltre non contengono la data, ma contengono il numero di bug che dovresti cercare in un sistema arcaico per trovare la data, quindi nessuno lo fa.


0

Non duplicare metadati che VCS sta per conservare per te. Le date e i nomi dovrebbero essere aggiunti automaticamente dal VCS. Numeri di ticket, nomi di manager/utenti che hanno richiesto la modifica, ecc. Dovrebbero essere nei commenti VCS, non nel codice.

Invece di questo:

// $ DATE $ NOME $ BIGLIETTO // utile commento alla prossima povera anima

farei questo:

commento

// utile per il prossimo povera anima


2

Lo faccio se la correzione di bug riguarda qualcosa che non è semplice, ma il più delle volte se il bugfix richiede una lunga spiegazione, lo prendo come un segno che la correzione non è stata progettata bene. Di tanto in tanto devo lavorare intorno a un'interfaccia pubblica che non può cambiare così questa tende ad essere la fonte di questi tipi di commenti, ad esempio:

// <date> [my name] - Bug xxxxx happens when the foo parameter is null, but 
// some customers want the behavior. Jump through some hoops to find a default value. 

In altri casi il controllo del codice sorgente messaggio di commit è quello che uso per annotare la modifica.


1

Spesso un commento del genere è più confuso, dal momento che non si dispone di un contesto specifico sul codice originale o sul cattivo comportamento originale.

In generale, se la correzione del bug ora esegue CORRETTAMENTE il codice, è sufficiente lasciarlo senza commenti. Non è necessario commentare il codice corretto.

A volte la correzione di bug rende le cose strane, o la correzione di bug sta verificando qualcosa fuori dall'ordinario. Quindi potrebbe essere opportuno avere un commento - di solito il commento dovrebbe fare riferimento al "numero di bug" dal database dei bug.Ad esempio, potresti avere un commento che dice "Bug 123 - Account per comportamento strano quando l'utente è in 640 per 480 risoluzione dello schermo".


2

Questo tipo di commenti è estremamente prezioso in un ambiente multi-sviluppatore in cui vi è una gamma di competenze e/o conoscenza del business tra gli sviluppatori (ad esempio, ovunque).

Per lo sviluppatore esperto e ben informato la ragione di un cambiamento può essere ovvia, ma per i nuovi sviluppatori che commentano li faranno riflettere due volte e fare ulteriori indagini prima di scherzare con esso. Aiuta anche a imparare di più su come funziona il sistema.

Oh, e una nota per esperienza sui "appena inseriti che nel sistema di controllo del codice sorgente" commenti:

Se non è nella fonte, non è successo.

Non riesco a contare il numero di volte in cui la storia di origine per i progetti è stato perso a causa di inesperienza con il software di controllo del codice sorgente, i modelli di ramificazione improprio ecc C'è solo posto la cronologia delle modifiche non può essere perduto - e questo è nel file sorgente.

Io di solito messo lì prima, quindi tagliare 'n incollare lo stesso commento quando ho check in.

+1

Non sono d'accordo qui. Cosa succede quando rifattori questo metodo? Ha senso cancellare anche il commento. 24 set. 082008-09-24 21:40:24

+1

Certo, l'eliminazione del vecchio codice e dei commenti associati va bene. È la parte che riguarda solo mettere i tuoi commenti in un sistema esterno che può perderli per te mentre sono ancora validi con cui non sono d'accordo. :-) 24 set. 082008-09-24 22:05:38

  0

Backup. Backup. Backup? 14 lug. 102010-07-14 17:12:48

+1

I backup non possono essere risolti in modo stupido. Vedi il paragrafo sull'inesperienza e modelli di ramificazione inadeguati. 14 lug. 102010-07-14 19:59:16


1

Se si aggiungono commenti del tipo che, dopo alcuni anni di mantenere il codice si avrà così tanti bug fix commenti non saresti in grado di leggere il codice.

Ma se si modifica qualcosa che sembra corretto (ma ha un bug sottile) in qualcosa che è più complicato, è bello aggiungere un breve commento che spiega cosa hai fatto, in modo che il prossimo programmatore per mantenere questo codice non cambi indietro perché lui (o lei) ti pensa cose troppo complicate senza una buona ragione.


0

Se il codice si trova su una piattaforma live, lontano dall'accesso diretto al repository di controllo sorgente, quindi aggiungerò commenti per evidenziare le modifiche apportate come parte della correzione per un bug sul sistema live.

In caso contrario, non il messaggio che si entra al check-in deve contenere tutte le informazioni necessarie.

applausi,

Rob


1

No. Io uso la sovversione ed entro sempre una descrizione della mia motivazione per aver commesso un cambiamento. In genere non ripeto la soluzione in inglese, ma riepilogo le modifiche apportate.

Ho lavorato su un numero di progetti in cui inserivano commenti nel codice quando venivano apportate correzioni di bug. È interessante notare che, e probabilmente non a caso, si trattava di progetti che non utilizzavano alcun tipo di strumento di controllo del codice sorgente o che avevano l'incarico di seguire questo tipo di convenzione con il mandato della direzione.

Onestamente, non ho davvero vedere il valore nel fare questo per la maggior parte delle situazioni. Se voglio sapere cosa è cambiato, guarderò il registro di sovversione e il diff.

Solo i miei due centesimi.


0

Quando eseguo correzioni di errori/miglioramenti in librerie/componenti di terze parti, faccio spesso alcuni commenti. Ciò semplifica la ricerca e lo spostamento delle modifiche se è necessario utilizzare una versione più recente della libreria/componente.

Nel mio codice raramente commento correzioni di errori.


0

Non lavoro su progetti di più persone, ma a volte aggiungo commenti su un determinato bug a un test di unità.

Ricorda, non esistono bug, solo test insufficienti.


0

Dato che faccio più TDD possibile (tutto il resto è suicidio sociale, perché ogni altro metodo ti costringerà a lavorare infinite ore), sistemo raramente bug.

maggior parte delle volte mi aggiungere osservazioni particolari come questo per il codice:

// I KNOW this may look strange to you, but I have to use 
// this special implementation here - if you don't understand that, 
// maybe you are the wrong person for the job. 

suoni aspri, ma la maggior parte delle persone che si definiscono "sviluppatori" non meritano altre osservazioni.


1

Se il codice viene corretto, il commento è inutile e mai interessante per nessuno - solo rumore.

Se il bug non viene risolto, il commento è errato. Allora ha senso. :) Quindi basta lasciare tali commenti se non hai davvero risolto il bug.