Qual è l'approccio migliore per i commenti di codice inline?

Stiamo eseguendo il refactoring di una base di codice legacy di 20 anni e sto discutendo con il mio collega sul formato dei commenti nel codice (plsql, java).

Non esiste un formato predefinito per i commenti, ma nella maggior parte dei casi le persone fanno qualcosa di simile nel commento:

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

il formato proposto per i commenti passati e futuri che desidero è:

// {yyyy-mm-dd}, unique_author_company_id, comment

Il mio collega afferma che abbiamo solo bisogno del commento e dobbiamo riformattare tutti i commenti passati e futuri in questo formato:

// comment

I miei argomenti:

• Dico per motivi di manutenzione, è importante sapere quando e chi ha fatto una modifica (anche questa informazione è contenuta nell'SCM).
• Il codice è vivo e per questo motivo ha una storia.
• Perché senza le date di modifica è impossibile sapere quando è stata introdotta una modifica senza aprire lo strumento SCM e cercare nella lunga cronologia degli oggetti.
• poiché l'autore è molto importante, un cambio di autori è più credibile di un cambio di autore
• Ragioni di agilità, nessuna necessità di aprire e navigare attraverso lo strumento SCM
• le persone avrebbero più paura di cambiare qualcosa che qualcuno ha fatto 15 anni fa, piuttosto che qualcosa che è stato recentemente creato o cambiato.
• eccetera.

Argomenti del mio collega:

• La storia è nel SCM
• Gli sviluppatori non devono essere a conoscenza della cronologia del codice direttamente nel codice
• I pacchetti sono lunghi 15k righe e i commenti non strutturati rendono questi pacchetti più difficili da comprendere

Quale pensi sia l'approccio migliore? O hai un approccio migliore per risolvere questo problema?

Commenti generali

Sono un grande sostenitore dei commenti per il perché (non come) . Quando inizi ad aggiungere commenti su come cadi nel problema che nulla impone che i commenti vengano mantenuti in relazione al codice (il perché di solito non cambierà (il perché la spiegazione potrebbe essere migliorata nel tempo)).

Allo stesso modo date / authorInfo non guadagna nulla in termini di perché il codice è stato fatto in questo modo; proprio come il modo in cui può degenerare nel tempo perché non c'è applicazione da parte di alcuno strumento. Inoltre, le stesse informazioni sono già memorizzate nel sistema di controllo del codice sorgente (quindi si sta duplicando lo sforzo (ma in modo meno affidabile)).

Passando attraverso gli argomenti:

Dico per motivi di manutenzione, è importante sapere quando e chi ha fatto una modifica (anche questa informazione è contenuta nell'SCM).

Perché. Nessuna di queste cose mi sembra importante per mantenere il codice. Se hai bisogno di parlare con l'autore è relativamente semplice trovare queste informazioni dal controllo del codice sorgente.

Il codice ha vita per quel motivo aveva una storia.

La cronologia è memorizzata nel controllo del codice sorgente.
Ti fidi anche che il commento sia stato scritto da quella persona. Howi commenti tendono a degradarsi nel tempo, quindi questo tipo di storia diventa inaffidabile. D'altro canto, i sistemi di controllo del codice sorgente mantengono una cronologia molto accurata e puoi vedere con precisione quando i commenti sono stati aggiunti / rimossi.

Perché senza la data di modifica è impossibile sapere quando è stata introdotta una modifica senza aprire lo strumento SCM e cercare nella lunga cronologia degli oggetti.

Se ti fidi dei dati in un commento.
Uno dei problemi con questo tipo di cose è che i commenti diventano errati in relazione al codice. Torna allo strumento corretto per il lavoro. Il sistema di controllo del codice sorgente lo farà correttamente senza che sia necessario l'intervento dell'utente. Se il tuo sistema di controllo del codice sorgente è un problema, forse devi imparare a usarlo in modo più appropriato (poiché tale funzionalità è di solito semplice) o se non lo supporta trova un sistema di controllo del codice sorgente migliore.

poiché l'autore è molto importante, un cambio di authorx è più credibile di un cambio di autore

Tutti gli autori (a parte te stesso) sono ugualmente credibili.

Ragioni di agilità, non è necessario aprire una navigazione nello strumento SCM

Se il tuo strumento di controllo del codice sorgente è così pesante che stai utilizzando in modo errato o (è più probabile) stai usando il set sbagliato di strumenti per accedere al sistema di controllo del codice sorgente.

la gente avrebbe paura di cambiare qualcosa che qualcuno ha fatto 15 anni fa, piuttosto che qualcosa che è stato fatto receantly ...

Se il codice è durato 15 anni, è più probabile che sia più solido del codice che è durato solo 6 mesi senza necessità di revisione. Il codice stabile tende a rimanere stabile, il codice errato tende a diventare più complesso nel tempo (poiché il motivo è errato è che il problema non è così semplice come si pensava inizialmente).

Ancora più motivi per utilizzare il controllo del codice sorgente per ottenere informazioni.

La storia è nel SCM

Sì. Il miglior motivo ancora.

Gli sviluppatori non devono essere a conoscenza della cronologia del codice direttamente nel codice

Se ho davvero bisogno di queste informazioni, le cercherò nel controllo del codice sorgente.
Altrimenti non è rilevante.

I pacchetti ottengono 15k righe e commenti non strutturati che questi pacchetti sono più difficili da comprendere

I commenti dovrebbero essere una descrizione del perché stai facendo qualcosa comunque.
I commenti NON devono descrivere come funziona il codice (a meno che l'algoritmo non sia ovvio).

Sostengo fortemente il tuo collega. Non ci riuscirai senza guardare lo SCM comunque se vuoi capire perché qualcosa è cambiato a meno che non conservi il vecchio codice in un commento.

Se il codice è troppo complesso per essere compreso senza scrivere tonnellate di commenti, suggerirei di investire energia nel refactoring per rendere il codice leggibile / mantenibile senza tonnellate di commenti.

Dopo tutto, assumi programmatori, non narratori di storie ;-)