Manutenzione del codice: aggiungere commenti nel codice o lasciarlo al controllo versione?

Ci è stato chiesto di aggiungere commenti con tag di inizio, tag di fine, descrizione, soluzione ecc. Per ogni modifica che apportiamo al codice come parte della correzione di un bug / implementazione di un CR.

La mia preoccupazione è che fornisce un valore aggiunto? Così com'è, abbiamo tutti i dettagli nella cronologia dei controlli di versione, che ci aiuteranno a tenere traccia di ogni singola modifica?

Ma i miei contatti insistono sull'avere i commenti come una "buona" pratica di programmazione. Uno dei loro argomenti è quando un CR deve essere declassato / modificato, sarebbe ingombrante se i commenti non fossero presenti.

Considerando che le modifiche sarebbero in gran parte tra i codici, sarebbe davvero utile aggiungere commenti per ogni singola modifica che facciamo? Non dovremmo lasciarlo al controllo della versione?

Hai assolutamente ragione. Tracciare le modifiche è il lavoro per il sistema di controllo della versione. Ogni volta che esegui un commit dovresti scrivere un messaggio di commit che spieghi cosa è stato fatto e facendo riferimento al tuo sistema di tracciamento dei bug se si tratta di una correzione di bug. Mettere un commento nel codice dicendo

// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX

ogni volta che correggi un bug renderai rapidamente il tuo codice illeggibile e irraggiungibile. Ciò comporterà anche la duplicazione delle stesse informazioni in due punti, il che peggiorerà ulteriormente il disordine.

I commenti non devono essere utilizzati per il tracciamento dei bug e non devono inoltre descrivere cosa sta facendo il codice. Dovrebbero spiegare perché stai facendo X o perché stai facendo X in questo modo particolare. Se senti la necessità di scrivere un commento che spieghi cosa sta facendo un blocco di codice, questo è un odore di codice che indica che dovresti trasformare questo blocco in una funzione con un nome descrittivo.

Quindi invece di

// fixed bug XXXXX on 10/9/2012

potresti avere un commento che dice

// doing X, because otherwise Y will break.

o

// doing X, because doing Y is 10 times slower.

Usa lo strumento migliore per il lavoro. Il sistema di controllo della versione dovrebbe essere lo strumento migliore per la registrazione in caso di correzione di errori e CR: registra automaticamente la data e chi ha apportato la modifica; non dimentica mai di aggiungere un messaggio (se lo hai configurato per richiedere i messaggi di commit); non annota mai la riga di codice errata o elimina accidentalmente un commento. E se il tuo sistema di controllo della versione sta già facendo un lavoro migliore dei tuoi commenti, è stupido duplicare il lavoro aggiungendo commenti.

La leggibilità del codice sorgente è fondamentale. Una base di codice ingombra di commenti che forniscono la cronologia completa di ogni correzione di bug e CR fatti non sarà affatto molto leggibile.

Ma non saltare completamente i commenti: i buoni commenti (non documentano in modo sbrigativo ogni avvio / arresto / descrizione / soluzione di ogni correzione di bug e CR) migliorano la leggibilità del codice. Ad esempio, per un pezzo di codice complicato o poco chiaro che aggiungi per correggere un bug, un commento del modulo che // fix ISSUE#413dice alle persone dove trovare maggiori informazioni nel tracker dei problemi è un'ottima idea.

I commenti nel codice riguardano ciò che il codice è in quel momento. Fare un'istantanea in un dato momento non dovrebbe fare riferimento a versioni precedenti (o peggio, future) del codice.

I commenti in VCS riguardano la modifica del codice. Dovrebbero leggere una storia sullo sviluppo.

Ora, ogni modifica dovrebbe includere commenti? nella maggior parte dei casi sì. L'unica eccezione che immagino è quando il comportamento previsto era già documentato ma non era quello che hai ottenuto, a causa di un bug. La correzione rende i commenti esistenti più precisi, quindi non devono essere modificati. Il bug stesso dovrebbe essere documentato nella cronologia dei ticket e nel commento di commit, ma solo nel codice se il codice sembra strano. In tal caso, a // make sure <bad thing> doesn't happendovrebbe essere sufficiente.

Un tipo di commento che apprezzo molto è:

// Questo è stato implementato per la Regola 5 della proposta 2

o qualunque diavolo usi per raccogliere le tue esigenze.

Questo ha due vantaggi, uno è che ti consente di trovare il motivo per cui hai implementato un determinato algoritmo senza cercare e un altro è che ti aiuterà a comunicare con ingegneri non software che lavorano su / creano i documenti dei requisiti.

Questo potrebbe non essere d'aiuto con i team più piccoli, ma se hai analisti che sviluppano le tue esigenze, può essere prezioso.

I tuoi suggerimenti sono giusti quando affermano che i commenti sono una buona pratica di programmazione, tuttavia ci sono eccezioni. L'aggiunta di un commento per ogni modifica apportata è una di queste. E hai ragione dicendo che questo dovrebbe appartenere al sistema di controllo della versione. Se devi conservare questi commenti in un unico posto, allora VCS è la strada da percorrere. I commenti nel codice sorgente tendono a diventare vecchi e non mantenuti. Nessun commento è molto meglio di un cattivo commento. Quello che non vuoi è avere commenti in entrambi i posti (nel codice e VCS) non sincronizzati. L'obiettivo è mantenere le cose ASCIUTTE avendo un'unica fonte di verità per le modifiche al codice.

Oltre a ciò che altri hanno detto, considera cosa succede se un cambiamento ha effetti a catena in tutto il sistema. Supponi di refactificare una parte di un'interfaccia principale nel processo di implementazione di una richiesta di modifica: quel tipo di modifica può facilmente toccare una grande percentuale dei file del codice sorgente in qualsiasi pezzo di software non banale con un importo che corrisponde a modifiche banali (classe o cambia il nome del metodo). Dovresti esaminare ogni singolo file toccato da tale operazione per annotarlo manualmente con tali commenti, piuttosto che fare affidamento sul VCS che fa tutto automaticamente? In un caso stai guardando a poco più di un lavoro di cinque minuti con qualsiasi strumento di refactoring decente seguito da una ricompilazione per assicurarti che nulla abbia interrotto la build, mentre l'altro può facilmente passare a un giorno di lavoro. Per quale vantaggio specifico?

Considera anche cosa succede quando sposti parti del codice. Uno degli sviluppatori di database con cui lavoro è in gran parte "ogni riga di SQL dovrebbe essere annotata con la revisione in cui è stata modificata, e faremo storie di revisione separate per ciascun file perché è più facile vedere chi ha cambiato cosa quando e perché ". Funziona piuttosto bene quando il cambiamento èsull'ordine di cambiare le singole linee. Non funziona altrettanto bene quando, come ho fatto recentemente per risolvere un grave problema di prestazioni, si interrompono parti di una query più ampia introducendo tabelle temporanee, quindi si cambia l'ordine di alcune query per adattarsi meglio al nuovo flusso di codice. Certo, il diff rispetto alla versione precedente era in gran parte insignificante poiché diceva che circa due terzi del file erano cambiati, ma il commento sul check-in era anche qualcosa come "una grande riorganizzazione per risolvere i problemi di prestazioni". Quando hai guardato manualmente le due versioni, era abbastanza chiaro che le parti grandi erano davvero le stesse, si spostavano solo. (E la procedura memorizzata in questione ha richiesto da più di mezzo minuto per l'esecuzione, a pochi secondi. A quel punto,

Con pochissime eccezioni, il rilevamento delle modifiche e la risoluzione dei problemi è opera di VCS, IMNSHO.

Di solito seguo questa regola: se la modifica è ovvia e il codice risultante non solleva domande, non ripristina o modifica sostanzialmente qualsiasi comportamento precedente in modo sostanziale, quindi lascialo al VCS per tracciare i numeri di bug e altre informazioni di modifica.

Tuttavia, se c'è un cambiamento che non è ovvio, che cambia la logica - specialmente cambia sostanzialmente la logica fatta da qualcun altro in modo non ovvio - può essere molto utile aggiungere qualcosa come "questo cambiamento è fare questo e che a causa del bug # 42742 ". In questo modo, quando qualcuno guarda il codice e si chiede "perché è qui? Questo sembra strano" ha una guida proprio davanti a lui e non deve fare indagini tramite VCS. Questo impedisce anche situazioni in cui le persone interrompono le modifiche altrui perché hanno familiarità con il vecchio stato del codice ma non si accorgono che è stato modificato da allora.

I commenti relativi al controllo della versione non appartengono al file di origine. Aggiungono solo disordine. Poiché è probabile che debbano essere collocati nello stesso posto (come un blocco di commenti nella parte superiore del file), causeranno conflitti di solo commento quando si uniscono rami paralleli.

Qualsiasi informazione di tracciamento che può essere estratta dal controllo versione non deve essere duplicata nel corpo del codice. Questo vale per idee stupide come le parole chiave di checkout di RCS $Log$e simili.

Se il codice viaggia mai al di fuori dell'ambito del sistema di controllo della versione, quella scia di commenti sulla sua storia perde contesto e quindi gran parte del suo valore. Per comprendere correttamente la descrizione della modifica, è necessario accedere alla revisione, in modo da poter visualizzare il diff alla versione precedente.

Alcuni vecchi file nel kernel Linux hanno blocchi di commenti cronologici di grandi dimensioni. Quelli risalgono a quando non esisteva un sistema di controllo della versione, solo tarball e patch.

I commenti nel codice dovrebbero essere minimi e precisi. Aggiunta di informazioni su difetto / modifica non preziose. Dovresti usare il controllo versione per questo. Qualche volta il controllo della versione offre un modo leggermente migliore di cambiare- Usiamo ClearCase UCM; Le attività UCM vengono create in base ai numeri di difetto, all'area di cambio ecc. (Ad es. Difetto29844_change_sql_to_handle_null).

I commenti dettagliati sono preferiti nei commenti sul check-in.

Preferisco includere dettagli sulle informazioni sul terreno, dettagli sulla soluzione NON implementata a causa di alcuni effetti collaterali.

Pramagic Programmer e CleanCode portano alle seguenti linee guida

Mantenere le conoscenze di basso livello nel codice, a cui appartiene, e riservare i commenti per altre spiegazioni di alto livello.