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

13

Stiamo eseguendo alcuni refactoring su una base di codice legacy di 20 anni e sto discutendo con il mio collega riguardo al 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 futuri e passati che desidero è:

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

Il mio collega dice 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 un cambiamento (anche questa informazione è in SCM).
  • Il codice è vivo e per questo motivo ha una cronologia.
  • Perché senza le date di modifica è impossibile sapere quando è stata introdotta una modifica senza aprire lo strumento SCM e cercare nella cronologia degli oggetti lunga.
  • perché l'autore è molto importante, un cambio di autori è più credibile di un cambio di autenticità
  • Motivi di agilità, nessuna necessità di aprire e navigare nello strumento SCM
  • le persone sarebbero più spaventate di cambiare qualcosa che qualcuno ha fatto 15 anni fa, di qualcosa che è stato creato o modificato di recente.
  • ecc.

Argomenti del mio collega:

  • La cronologia è in SCM
  • Gli sviluppatori non devono conoscere la cronologia del codice direttamente nel codice
  • I pacchetti ottengono lunghe righe di 15k e i commenti non strutturati rendono questi pacchetti più difficili da capire

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

    
posta Diego Alvarez 07.11.2012 - 21:53
fonte

2 risposte

33

Commenti generali

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

Allo stesso modo data / authorInfo non ti 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'è l'applicazione da parte di nessuno strumento. Anche le stesse informazioni sono già memorizzate nel sistema di controllo del codice sorgente (quindi stai duplicando lo sforzo (ma in modo meno affidabile)).

Passando attraverso gli argomenti:

I say for maintenance reasons, it's important to know when and who did a change (even this information is in the SCM).

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

The code has life for that reason had an history.

La cronologia è memorizzata nel controllo sorgente.
Inoltre ti fidi che il commento è stato scritto da quella persona. I commenti di How tendono a peggiorare nel tempo, quindi questo tipo di storia diventa inaffidabile. D'altro canto, i sistemi di controllo del codice sorgente manterranno una cronologia molto accurata e potrai vedere con precisione quando i commenti sono stati aggiunti / rimossi.

Because without the change date it's impossible to know when a change was introduced without open the SCM tool and search in the long object history.

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 lo farà correttamente, senza necessità di intervento da parte dell'utente. Se il tuo sistema di controllo del codice sorgente è un problema allora forse hai bisogno di imparare come usarlo in modo più appropriato (in quanto tale funzionalità è solitamente semplice) o se non lo supporta trova un sistema di controllo del codice sorgente migliore.

because the author is very important, a change of authorx is more credible than a change of authory

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

Agility reasons, no need to open an navigate the SCM tool

Se il tuo strumento di controllo del codice sorgente è così oneroso, lo stai usando male o (è più probabile) stai usando il set di strumenti sbagliato per accedere al sistema di controllo del codice sorgente.

people would be afraid of change something that someone did 15 years ago, than someting that was receantly made ...

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

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

The history is in the SCM

Sì. La migliore ragione ancora.

Developers must not be aware of history of the code directly in the code

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

Packages gets 15k lines long and unstructured comments this packages harder to understand

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

    
risposta data 07.11.2012 - 21:58
fonte
6

Sostengo fermamente il tuo collega. Non riuscirai a cavartela senza guardare allo SCM comunque se vuoi capire perché qualcosa è stato cambiato a meno che non mantieni il vecchio codice in un commento.

Se il codice è troppo complesso per essere compreso senza scrivere tonnellate di commenti, ti suggerirei di investire le tue energie nel refactoring per rendere il codice leggibile / controllabile senza tonnellate di commenti.

Dopo tutto, assumi programmatori, non narratori; -)

    
risposta data 07.11.2012 - 21:55
fonte

Leggi altre domande sui tag