Usi commenti speciali su correzioni di errori nel tuo codice?

Question

Alcuni miei colleghi usano commenti speciali sulle loro correzioni di bug, ad 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.

Answer 1

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 il motivo per cui si sta facendo qualcosa di non ovvio. Quindi se la correzione dei bug rende il codice meno prevedibile e chiaro, allora spiego perché.

Answer 2

Nel tempo questi possono accumularsi e aggiungere disordine. È meglio chiarire il codice, aggiungere eventuali commenti per gotcha correlati che potrebbero non essere ovvi e mantenere i dettagli dei bug nel sistema di tracciamento e nel repository.

Answer 3

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

  

[ID bug] Problema con la finestra di dialogo xyz.   Codice di dimensionamento spostato su abc e ora   inizializza più tardi.

Quindi, nel mio tracker dei problemi, farò qualcosa del tipo:

  

Risolto nell'elenco modifiche 1234.

     

Codice di dimensionamento spostato su abc e ora   inizializza più tardi.

Perché allora rimane un buon marcatore storico. Inoltre, è facile se vuoi sapere perché una determinata riga di codice è in un certo modo, puoi semplicemente guardare la cronologia dei file. Una volta trovata la riga di codice, puoi leggere il mio commento di commit e vedere chiaramente quale bug era e come l'ho risolto.

Answer 4

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

Answer 5

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é come consulente aggiorno spesso il codice di altre persone.

// Glenn F. Henriksen (<email@company.no) - 2008-09-23
// <Short description>

In questo modo i proprietari del codice, o le persone che vengono dopo di me, possono capire cosa è successo e possono mettersi in contatto con me se devono.

(sì, sfortunatamente, il più delle volte non hanno alcun controllo del codice sorgente ... per cose interne utilizzo il tracciamento TFS)

Answer 6

Anche se al momento può sembrare una buona idea, sfugge rapidamente di mano. Tali informazioni possono essere acquisite meglio utilizzando una buona combinazione di sistema di controllo del codice sorgente e bug tracker. Ovviamente, se c'è qualcosa di complicato, 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 attualmente lavorando al lavoro ha qualcosa come 20 anni e sembra che abbiano 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 in tutto il codice e la politica ora è "rimuoverli se si lavora direttamente su quel codice, ma altrimenti lasciarli". Spesso sono davvero 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.

Answer 7

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

Answer 8

Lo faccio se la correzione di bug implica qualcosa che non è semplice, ma il più delle volte se la correzione di bug richiede una lunga spiegazione, la prendo come un segno che la correzione non è stata progettata bene. Occasionalmente devo aggirare un'interfaccia pubblica che non può cambiare, quindi tende ad essere la fonte di questo tipo 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 messaggio di commit del controllo del codice sorgente è quello che uso per annotare la modifica.

Answer 9

Mentre tendo a vedere alcuni commenti sui bug all'interno del codice al lavoro, la mia preferenza personale è quella di collegare un commit del codice a un bug. Quando ne dico uno intendo davvero un bug. Successivamente puoi sempre guardare le modifiche apportate e sapere a quale bug sono state applicate.

Answer 10

Questo stile di commento è estremamente prezioso in un ambiente multi-sviluppatore in cui vi è una gamma di competenze e / o conoscenze aziendali tra gli sviluppatori (ad esempio, ovunque).

Per lo sviluppatore esperto esperto il motivo di una modifica può essere ovvio, ma per gli sviluppatori più recenti che commentano faranno riflettere due volte e fare ulteriori indagini prima di fare confusione. Li aiuta anche a saperne di più su come funziona il sistema.

Oh, e una nota per esperienza relativa a " l'ho appena inserita nel sistema di controllo sorgente " commenti:

Se non è nella fonte, non è successo.

Non riesco a contare il numero di volte in cui la cronologia dei sorgenti è stata persa a causa di inesperienza con il software di controllo del codice sorgente, modelli di ramificazione non corretti ecc. solo un posto dove la cronologia delle modifiche non può essere persa - e si trova nel file di origine.

Di solito lo metto prima lì, quindi taglia e incolla lo stesso commento quando lo controllo.

Answer 11

No, non lo so, e odio avere graffiti come quelli che sporcano il codice. I numeri di bug possono essere tracciati nel messaggio di commit nel sistema di controllo versione e tramite script per inviare messaggi di commit rilevanti nel sistema di tracciamento dei bug. Non credo che appartengano al codice sorgente, in cui le modifiche future confonderanno semplicemente le cose.

Answer 12

Spesso un commento del genere è più confuso, dal momento che non si ha davvero un contesto sull'aspetto del codice originale o sul cattivo comportamento originale.

In generale, se ora la correzione del tuo bug fa funzionare CORRETTAMENTE il codice, lascialo semplicemente senza commenti. Non è necessario commentare il codice corretto.

A volte la correzione di bug rende le cose strane o la correzione di bug sta testando qualcosa di fuori dal comune. Quindi potrebbe essere appropriato avere un commento - di solito il commento dovrebbe fare riferimento al "numero di bug" dal tuo database di bug. Ad esempio, potresti avere un commento che dice "Errore 123 - Tieni conto del comportamento strano quando l'utente ha una risoluzione dello schermo di 640 per 480".

Answer 13

Se aggiungi commenti del genere dopo alcuni anni di manutenzione del codice, avrai così tanti commenti sulla correzione di errori che non riusciresti a leggere il codice.

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

Answer 14

No. Uso sovversione e inserisco sempre una descrizione della mia motivazione per commettere un cambiamento. In genere non ribadisco la soluzione in inglese, ma riassumo le modifiche apportate.

Ho lavorato su numerosi progetti in cui hanno inserito commenti nel codice quando sono state apportate delle correzioni di bug. È interessante notare che, probabilmente, non a caso, si trattava di progetti che o non utilizzavano alcun tipo di strumento di controllo del codice sorgente o erano incaricati di seguire questo tipo di convenzione da parte di Fiat.

Onestamente, non vedo davvero 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.

Answer 15

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

Se il bug non viene risolto, il commento è errato. Quindi ha senso. :) Quindi lascia questi commenti se non hai risolto il bug.

Answer 16

Per individuare un commento specifico utilizziamo DKBUGBUG - il che significa che la correzione e il revisore di David Kelley possono facilmente identificarsi, Ofcourse aggiungeremo Data e altri numeri di tracciamento dei bug VSTS ecc. insieme a questo.

Answer 17

Non duplicare i metadati che il tuo VCS manterrà per te. Date e nomi devono essere aggiunti automaticamente dal VCS. I numeri dei biglietti, i nomi dei gestori / utenti che hanno richiesto la modifica, ecc. Devono essere inclusi nei commenti VCS, non nel codice.

Piuttosto che questo:

// $ DATE $ NAME $ TICKET // utile commento alla prossima povera anima

Vorrei fare questo:

// utile commento alla prossima povera anima

Answer 18

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

Altrimenti, nessun messaggio inserito al momento del check-in deve contenere tutte le informazioni necessarie.

applausi,

Rob

Answer 19

Quando apporto correzioni / miglioramenti a librerie / componenti di terze parti, faccio spesso dei 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.

Answer 20

Non lavoro su progetti per più persone, ma a volte aggiungo commenti su un determinato bug a un test unitario.

Ricorda, non esistono bug, solo test insufficienti.

Answer 21

Dato che faccio il maggior numero possibile di TDD (tutto il resto è un suicidio sociale, perché ogni altro metodo ti costringerà a lavorare per infinite ore), raramente correggo bug.

La maggior parte delle volte aggiungo al codice osservazioni speciali come questa:

// 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.

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