È buona norma commentare con il numero di rilascio?

In generale, non lo considererei una buona pratica. Ma in casi eccezionali, può essere molto utile, in particolare quando il codice deve fare qualcosa di non intuitivo per risolvere un problema complesso, e senza alcuna spiegazione ci sarebbe il rischio che qualcuno possa voler "aggiustare" questo strano codice e quindi romperlo , mentre spiegare il ragionamento si tradurrebbe in un enorme commento che duplica le informazioni dal problema.

Penso che sia sufficiente aggiungere il numero di problema al messaggio di commit quando si commette la correzione correlata al sistema di controllo del codice sorgente.

Ad esempio:

Bug #203: Database connections no longer time out after 30 seconds.

Trovo che l'aggiunta di numeri di rilascio, nomi di sviluppatori o date che sono state apportate modifiche nel codice inquina solo la base di codice e dovrebbe essere gestita esternamente dal sistema di controllo del codice sorgente.

Non sono assolutamente d'accordo con gli altri poster qui!

I commenti di codice con riferimenti di tracciamento possono essere di grande aiuto per la programmazione di manutenzione.

Se sto rintracciando un bug e avvicinandomi all'area del codice, per vedere che è stato recentemente cambiato e avere un link nel contesto del cambiamento è un dio-invio.

Sì, abbiamo il controllo del codice sorgente, ma può essere piuttosto lento per controllare individualmente file e moduli. vuoi queste cose per farti saltare le modifiche recenti.

Probabilmente li deprecherò perché vedo codici molto vecchi nella base di codice, ma c'è molto poco altro in cui tenere quelli più recenti e un sacco di tempo di sviluppo potenzialmente risparmiato se li usi in modo intelligente.

In realtà penso che questi piccoli riferimenti al sistema di tracciamento dei bug siano preferibili ai commenti dettagliati nel codice.

Se ti iscrivi a un criterio di "Codice pulito", allora probabilmente devi chiederti se è buona norma aggiungere commenti. Se il codice può essere chiarito solo con un commento, quindi sicuro, aggiungine uno, altrimenti dovresti essere in grado di capire facilmente che cosa fa il tuo codice semplicemente leggendolo (purché tu stia usando nomi ragionevoli per le tue variabili, metodi, ecc.).

Indipendentemente dalla tua opinione personale sul fatto che il commento sia una buona pratica o meno, un commento dovrebbe contenere informazioni che sono di valore diretto per il codice a cui il commento si riferisce. In questo caso, la domanda è se l'aggiunta di un numero di problema aggiunge valore al codice. Il problema che vedo con l'aggiunta del numero di problema è che si può avere una sezione di codice che potrebbe essere pesantemente modificata per soddisfare diversi problemi e, dopo un po ', potrebbe essere impossibile identificare correttamente quali modifiche si sono riferite a un problema specifico. I problemi successivi, ad esempio, potrebbero richiedere un pesante refactoring del codice relativo ai problemi precedenti. Questo è forse un esempio estremo, tuttavia mostra come i numeri dei numeri nei commenti nel codice possono rivelarsi piuttosto inutili.

Se potessi garantire che la situazione che ho appena descritto non accadrà mai, continuerei a sostenere che il numero del problema stesso è ancora abbastanza inutile senza una descrizione del problema, e tuttavia, tutte queste informazioni sono davvero appartiene al tuo sistema di tracciamento dei problemi e dovrebbe essere duplicato. Un posto migliore per notare che il numero del problema è nel proprio sistema di controllo della versione come commento di commit. Il vantaggio è che puoi confrontare le versioni e vedere le modifiche al codice relative a un problema specifico, mentre il numero del problema stesso ti fornisce l'identificatore necessario se vuoi esaminare il motivo della modifica del codice.

Tenendo presente tutto ciò, suggerirei che non è davvero una buona pratica aggiungere numeri di rilascio nei commenti all'interno del codice.

Penso che sia una buona pratica riferirsi a un problema per ulteriori letture, dando una breve spiegazione nel commento stesso.

Solitamente aggiungo commenti solo se c'è qualcosa di sottile o non intuitivo in quel pezzo di codice. Poiché alcuni problemi delicati non possono essere spiegati completamente in poche righe, e non voglio aggiungere decine di righe di commenti, aggiungerei un breve commento che descrive cosa sta cercando di ottenere, e rimando al problema per i dettagli.

Ad esempio:

// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details

Dove il problema 123 descrive come potrebbe essere l'attacco e perché il nuovo codice è immune all'attacco.

o

// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.

Il problema principale con l'inserimento dei numeri di problema nella tua fonte è che ora hai un riferimento esterno. Quindi devi essere sicuro di non perdere il problema.

Includere il numero di problema nei messaggi di commit può essere molto utile quando il codice sorgente è cablato con integrazione continua. Applicazioni come TeamCity estrarranno tali informazioni e consentiranno una migliore segnalazione.

Con quanto detto sopra, non sono sicuro al 100% che derivi dai commenti al codice. Includere numeri di numeri nel codice funziona bene se i numeri dei problemi sono persistenti (ad esempio, non si modificano i tracker dei problemi) e non si hanno molti problemi per un dato progetto.

Probabilmente è più utile se descrivi il problema e la soluzione in modo che il prossimo sviluppatore non abbia bisogno di cercare il numero del problema. Il compilatore o il minificatore rimuoveranno i tuoi commenti solo prima che il codice venga rilasciato in modo che non ci sia alcun impatto sul risultato finale.