Ho visto molti numeri di problema dai commenti del codice jQuery . (In realtà, c'erano 69 numeri di emissione nel codice jQuery.) Penso che sarebbe una buona pratica, ma non ho mai visto linee guida.
Se è una buona pratica, quali sono le linee guida per questa pratica?
Risposte:
In generale, non la considero una buona pratica. Ma in casi eccezionali, può essere molto utile, vale a dire 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 "riparare" questo strano codice e quindi romperlo , mentre spiega il ragionamento si tradurrebbe in un enorme commento che duplica le informazioni dal problema.
Penso che sia sufficiente aggiungere il numero del problema al messaggio di commit quando si esegue il commit della correzione correlata al sistema di controllo del codice sorgente.
Per esempio:
Bug n. 203: le connessioni al database non scadono più dopo 30 secondi.
Trovo che l'aggiunta di numeri di emissione, nomi di sviluppatori o date in cui sono state apportate modifiche al codice inquina solo la base di codice e dovrebbe essere realmente gestita esternamente dal sistema di controllo del codice sorgente.
Non sono completamente d'accordo con gli altri poster qui!
I commenti di codice con riferimenti di tracciamento possono essere di grande aiuto per la programmazione della manutenzione.
Se sto rintracciando un bug e mi sto avvicinando all'area del codice, vedere che è stato modificato di recente e avere un link al contesto della modifica è un god-send.
Sì, abbiamo il controllo del codice sorgente, ma può essere abbastanza lento controllare singoli file e moduli. Vuoi che queste cose ti saltino fuori per le recenti modifiche.
Probabilmente li deprecerei perché vedo quelli molto vecchi nella base di codice, ma c'è molto poco lato negativo nel mantenere 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 tuo sistema di tracciamento dei bug siano preferibili a commenti dettagliati nel codice.
git gui blame <filename>fornisce una GUI molto veloce per sfogliare la cronologia del codice se usi git. L'uso di uno strumento per combinare i commenti sul codice con la cronologia consente una documentazione molto migliore per il codice di qualsiasi altro commento incorporato. Cioè, se ti preoccupi di scrivere buoni messaggi di commit (un buon messaggio di commit dovrebbe essere approssimativamente uguale a un messaggio di posta elettronica che spiega perché quella patch dovrebbe essere applicata).
Se ti iscrivi a una politica di "Clean Code", probabilmente dovrai chiederti se è buona norma aggiungere commenti. Se il codice può essere chiarito solo con un commento, assicurati di aggiungerne uno, altrimenti dovresti essere in grado di capire facilmente cosa fa il tuo codice semplicemente leggendolo (a condizione che tu stia usando nomi sensibili per le tue variabili, metodi, ecc.).
Indipendentemente dalla tua opinione personale sul fatto che commentare sia una buona pratica o meno, un commento dovrebbe contenere informazioni di valore diretto per il codice a cui si riferisce il commento. 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 del problema è che puoi avere una sezione di codice che potrebbe essere modificata pesantemente per soddisfare diversi problemi e, dopo un po ', potrebbe essere impossibile identificare correttamente quali modifiche sono correlate a un problema specifico. I problemi successivi, ad esempio, potrebbero richiedere che il codice relativo a problemi precedenti sia sottoposto a un pesante refactoring. Questo è forse un esempio estremo, tuttavia mostra come i numeri dei problemi nei commenti nel codice possano risultare piuttosto inutili.
Se potessi garantire che la situazione che ho appena descritto non si verificherebbe mai, direi comunque che il numero del problema stesso è ancora piuttosto inutile senza una descrizione di ciò che riguarda il problema, eppure, tutte queste informazioni appartengono davvero al tuo sistema di tracciamento dei problemi e dovrebbe essere duplicato. Un posto migliore per annotare il numero del problema sarebbe nel 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 desideri esaminare il motivo della modifica del codice.
Con tutto ciò in mente, suggerirei che non è davvero una buona pratica in quanto aggiungere numeri di problema nei commenti all'interno del codice.
Penso che sia buona norma fare riferimento a un problema per ulteriori letture, fornendo una breve spiegazione nel commento stesso.
In genere aggiungo commenti solo se c'è qualcosa di sottile o non intuitivo in quel pezzo di codice. Dal momento che alcuni problemi impercettibili non possono essere spiegati completamente in poche righe e non voglio aggiungere dozzine di righe di commenti, aggiungerei un breve commento che descriva ciò che questo sta cercando di ottenere e fare riferimento al problema per dettagli.
Per esempio:
// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details
Dove il numero 123 descrive l'aspetto di quell'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 un migliore reporting.
Con quanto detto sopra non sono sicuro al 100% che tira dai commenti sul codice. Includere i numeri di problema nel codice funziona bene se i numeri di problema persistono (ad es. Non si modificano i tracker dei problemi) e non si hanno molti problemi per un determinato 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 rimuoverà i tuoi commenti prima che il codice venga rilasciato in natura, quindi non dovrebbe esserci alcun impatto sul risultato finale.