È utile includere un "registro delle modifiche" in ogni file di codice quando si utilizza il controllo versione?

75

Avevo l'impressione che un sistema di controllo della versione eliminasse la necessità di avere "log delle modifiche" intonacati ovunque nel codice. Ho spesso visto l'uso continuo dei registri delle modifiche, inclusi grandi blocchi lunghi all'inizio delle procedure memorizzate con una grande sezione bloccata per le modifiche al file e sporcare il codice con cose come:

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

e:

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

La ragione di ciò, come mi è stato spiegato, è che ci vuole troppo tempo per setacciare i nostri log VCS cercando di trovare chi ha cambiato cosa e perché, pur avendo nel file di codice stesso, in alto o vicino al relativo cambiare, rende facile vedere chi ha cambiato cosa e quando. Anche se ne vedo il punto, sembra ridondante e sembra un po 'di "Eh non capiamo davvero come usare correttamente il nostro VCS, quindi non ci preoccuperemo affatto di quella roba."

Cosa ne pensi? Usi sia i commenti che il registro? Solo il registro? Trovi che sia più facile codificare quando puoi vedere sopra un blocco di codice che John Smith ha cambiato il metodo per controllare XYZ una settimana fa, invece di dover cercare nei registri e confrontare i file di codice in uno strumento Diff?

EDIT: utilizzando SVN, ma sostanzialmente solo come repository. Niente rami, niente fusioni, niente tranne log + archiviazione.

version-control coding-standards maintenance

— Wayne Molina
fonte

4

Quale sistema di controllo versione stai usando?

— ChrisF

11

Alcuni negozi utilizzavano i registri delle modifiche prima che esistessero i sistemi di controllo del codice sorgente. L'inerzia e la familiarità mantengono il registro delle modifiche.

— Gilbert Le Blanc,

2

+1 - Anche il mio team lo fa, e ho cercato di convincere alcuni di loro che è il ruolo del VCS. Il problema inizia quando questi commenti non vengono aggiornati con il codice reale ... E il peggio è che il management ha deciso di aggiungere anche i log delle modifiche a ogni metodo.

— slaphappy,

2

+1 - Ho combattuto con il nostro sviluppatore senior per quasi due anni a riguardo. La sua unica logica per l'aggiunta di questi commenti inutili è che rende un po 'più semplice la fusione delle modifiche ai metodi a 3000 righe. L'idea che un metodo di 3000 linee sia osceno è accolta con disprezzo.

— Joshua Smith,

1

Se "impiega troppo tempo a esaminare i [tuoi] registri VCS", stai facendo qualcosa di sbagliato.

— Keith Thompson,

46

Tendo a eliminare i commenti nel codice. E per cancellazione, intendo, con pregiudizio . A meno che un commento non spieghi perché una particolare funzione fa qualcosa, scompare. Ciao ciao. Non passare, vai.

Quindi non dovrebbe sorprenderti se anche io cancellassi quei log delle modifiche, per lo stesso motivo.

Il problema con il codice commentato e i commenti che leggono come libri è che non sai davvero quanto sia rilevante e ti dà un falso senso di comprensione su ciò che il codice effettivamente fa.

Sembra che il tuo team non abbia buoni strumenti per il tuo sistema di controllo versione. Dato che hai detto che stai usando Subversion, vorrei sottolineare che ci sono molti strumenti che ti aiuteranno a gestire il tuo repository Subversion. Dalla possibilità di navigare attraverso il Web, fino al collegamento dei changeset a specifici bug, puoi fare molto per mitigare la necessità di questi "log delle modifiche".

Ho avuto molte persone che commentano e dicono che forse sono in errore per l'eliminazione dei commenti. La stragrande maggioranza del codice che ho visto è stato commentato è stato un codice errato e i commenti hanno solo offuscato il problema. In effetti, se mai commenterò il codice, puoi essere certo che sto chiedendo perdono al programmatore di manutenzione perché sono relativamente certo che vorranno uccidermi.

Ma per non pensare che dico che i commenti dovrebbero essere cancellati per scherzo, questa presentazione del WTF giornaliera (da una base di codice su cui ho lavorato) illustra perfettamente il mio punto:

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

Oh ... Le storie che potrei raccontarti su quella base di codice, e vorrei, tranne che è ancora in uso da una delle più grandi organizzazioni governative in circolazione.

— George Stocker
fonte

4

Ogni volta che faccio fatica con un particolare pezzo di logica complessa, a volte i commenti possono aiutarmi a capire qual è il motivo per cui la logica è così contorta quanto lo è. Ma nel complesso sono d'accordo con te.

— maple_shaft

5

Ogni sviluppatore ha almeno alcune cattive qualità, so che non dovrei ma non riesco proprio a smettere :) Ogni volta che creo un TODOcommento muore un cucciolo.

— maple_shaft

32

Eliminare i commenti di altre persone con pregiudizio è un modo per forzare il proprio stile di programmazione e la convinzione sugli altri. I programmatori junior e pacifisti non abbaiano, ma di tanto in tanto ti imbatti in un maschio alfa e quindi inizia un combattimento che non avrebbe dovuto iniziare. Quindi, hai letto su un blog intelligente di una persona intelligente che quando si tratta di commenti, meno è di più. Altri potrebbero non aver letto lo stesso libro. Anche se pensi di avere ragione perché alcune persone su SO con 5k + rep concordano, la dittatura non è la strada da percorrere per il lavoro collaborativo. Prima ho lavorato con un maschio alfa e ho smesso.

— Giobbe

8

@Neil Butterworth: ri: ructions: il codice è pensato per essere malleabile. Rifattattilo, modificalo, miglioralo. È pensato per quello. Non è pensato per essere scritto solo una volta. La nostra comprensione dei cambiamenti aziendali e quando ciò accade dobbiamo cambiare il codice. Ho molti problemi con i commenti, ma la cosa più rilevante per la nostra discussione è che i commenti raramente rimangono sincronizzati con il codice, e generalmente non spiegano perché sta accadendo qualcosa. Quando ciò accade, è facile eliminarlo. Se qualcuno viene da me e mi chiede perché ho eliminato il seguente commento file.Open() // Open the file. Riderei.

— George Stocker,

5

Pochi giorni fa, ho scritto un pezzo di codice, un calcolo matematico molto complesso pieno di trigonometria, trasformazioni, qualunque cosa ... Mi ci sono voluti circa un'ora e mezza per scrivere meno di 10 righe di codice. Praticamente nessuno intorno a me capisce come funziona. Non lo capirò anche tra qualche settimana. D'altra parte, perché è banale. Quindi, sopra quelle poche righe, c'è un intero capitolo di testo, che spiega cosa, non perché. Se venissi e cancellassi quel commento, ti avrei dato un pugno in faccia, sparando a morte.

— Davor Ždralo,

76

Quei "log delle modifiche" incorporati nel codice sono particolarmente naff. Mostrano solo l'ennesima differenza quando fai le revisioni delle differenze, e quella a cui non ti interessa davvero. Fidati del tuo VCS - la maggior parte ha una funzione di "colpa" che ti mostrerà molto rapidamente chi ha cambiato cosa.

Ovviamente la cosa davvero orribile era quella caratteristica dei VCS "vecchi tempi" in cui si poteva avere il registro VCS effettivo incorporato nei file di origine. La fusione è diventata quasi impossibile.

— Neil Butterworth
fonte

14

Non solo mostrano un'altra differenza, peggio, ma possono anche sbagliarsi nel tempo, mentre ogni buon VCS sarà sempre in grado di dirti chi ha davvero scritto una determinata riga, così come la storia attorno a quella linea. L'unica cosa peggiore dei commenti inutili sono i commenti dannosi. Questi commenti iniziano come inutili e alla fine diventano dannosi, se non totalmente ignorati.

— Ben Hocking,

10

Ho un singolo file ChangeLog per ogni progetto che viene automaticamente popolato da determinati messaggi di commit.

Non abbiamo commenti ChangeLog incorporati. Se lo facessimo li rimuoverei e farei una "conversazione" con la persona che li aggiunge. Penso che siano indicativi di non capire gli strumenti che usi, in particolare i vcs.

Abbiamo un formato per i messaggi di commit che semplifica il grep dei log. Non consentiamo inoltre messaggi di commit inutili o ambigui.

— dietbuddha
fonte

8

Personalmente detesto i log delle modifiche all'interno del file sorgente del codice. Per me è come se violasse un principio di ingegneria del software in quanto ogni modifica che faccio deve essere effettuata in più punti. Molte volte le informazioni del registro delle modifiche sono completamente inutili e non importanti. A mio modesto parere, le modifiche al software dovrebbero essere documentate quando si controlla il codice.

Ma cosa so ...

Penso che se si insiste sull'implementazione della pratica di mantenere un registro delle modifiche all'interno del codice sorgente, il registro delle modifiche dovrebbe essere limitato alle modifiche che incidono sull'API / interfaccia pulic della classe. Se stai apportando modifiche all'interno della classe che non infrangono alcun codice che la utilizza, la registrazione di queste modifiche in un registro delle modifiche è solo un disordine a mio avviso. Tuttavia, posso vedere come a volte può essere utile poter controllare la parte superiore del file del codice sorgente per la documentazione su eventuali modifiche che potrebbero aver rotto qualcosa per chiunque altro. Solo un riepilogo di come la modifica potrebbe influire sull'API e perché è stata apportata la modifica.

D'altra parte, il mio negozio fa principalmente cose in C # e usiamo sempre commenti XML in linea per documentare la nostra API, quindi leggere la documentazione sulle modifiche dell'API pubblica è più o meno semplice come usare intellisense.

Penso che insistere su un registro delle modifiche all'interno del file di origine sia solo aggiungere inutili attriti alla macchina e sconfiggere uno degli scopi dell'implementazione di un sistema di controllo della versione in primo luogo.

— John Connelly
fonte

6

L'ultima società in cui ho lavorato aveva un software con alle spalle 17 anni di storia, sviluppo e aggiornamenti annuali. Non tutte le migrazioni da un sistema di controllo versione a quello successivo conserverebbero commenti o note di check-in. Né tutti gli sviluppatori in quegli anni hanno mantenuto la coerenza con i commenti / le note relativi al check-in.

Con commenti nel codice sorgente, la storia archeologica delle modifiche è stata mantenuta come nota, non come commento. E, sì, stanno ancora spedendo il codice VB6.

— Tangurena
fonte

5

Il controllo della versione può sostituire i commenti del registro delle modifiche nel codice se gli sviluppatori del tuo team lo stanno utilizzando correttamente.

Se il tuo team non sta aggiungendo commenti al momento del check-in o sta lasciando commenti inutili, sarà difficile trovare le informazioni che stai cercando in futuro.

Nella mia azienda attuale, siamo tenuti a inviare un commento ad ogni check-in. Non solo, ma dobbiamo allegare ogni check-in con un biglietto a Jira. Quando guarderai in Jira in futuro, puoi vedere tutti i file che erano stati archiviati e quando per quel problema insieme al commento che era rimasto. È abbastanza utile.

Fondamentalmente, il controllo della versione è solo uno strumento, è il modo in cui il tuo team utilizza quello strumento che fornirà i vantaggi che stai cercando. Tutti i membri del team devono essere d'accordo su come lo useranno per fornire al meglio il monitoraggio delle correzioni di bug e le revisioni del codice pulito.

— Tyanna
fonte

5

Questo è un residuo dei giorni in cui i registri VCS erano confusi e i sistemi VCS erano difficili da gestire (ricordo quei giorni, da qualche parte nel backend degli anni '80).

Il tuo sospetto è del tutto corretto, questi commenti sono più un ostacolo che un aiuto e qualsiasi VCS moderno ti permetterà di trovare esattamente quello che stai cercando. Certo, tu (e i tuoi colleghi) dovrete spendere ca. 30-60 minuti imparando a guidare tutte queste funzionalità (che, sospetto, è in realtà il motivo per cui questi commenti sono ancora lì).

Lo tengo (quasi) con George. I commenti nel codice sono davvero giustificati solo se spiegano qualcosa che non è immediatamente visibile nel codice stesso. E ciò accade solo raramente con un buon codice. Se hai bisogno di avere molti commenti nel tuo codice, questo è un suo odore e grida "refactor me!".

— wolfgangsz
fonte

4

Li includiamo ancora nell'origine della procedura memorizzata perché è così che possiamo dire esattamente quale versione è presente in un client. Il resto dell'applicazione è distribuito compilato, quindi abbiamo numeri di versione del modulo che rimandano all'origine, ma gli SP sono distribuiti come origine ai client per la compilazione locale nel database.

Il nostro codice precedente di PowerBuilder li utilizza ancora, ma penso che sia solo un fattore di comfort per alcuni pigoli. Anche questo viene compilato per la distribuzione, quindi (IMO dovrebbero) usare la frigginosa storia di VCS.

— Davee
fonte

1

+1 Stavo per scrivere questa risposta ma mi hai salvato il problema. Non solo le stored procedure sono distribuite come origine, ma anche molti linguaggi di scripting. Uso molto OpenACS e TCL - spesso se un client ha una versione biforcuta di un determinato file, l'unico modo per essere GARANTITO di sapere quale versione è è leggere il registro delle modifiche. Particolarmente utile se si è connessi al sito di un client e non è possibile fare facilmente differenze con il software di controllo della versione.

— TrojanName

3

Se stai usando SVN, farlo è una perdita di tempo e totalmente inutile.

SVN ha la funzione di colpa. Questo ti dirà esattamente chi ha fatto ogni riga in un dato file e quando.

— comesichiama
fonte

1

I commenti del registro delle modifiche sono estremamente utili nel codice quando aiutano uno sviluppatore successivo a porre domande migliori in merito ai nuovi requisiti. Quando uno sviluppatore vede un commento, ad esempio, che Fred ha reso il campo Foo richiesto 6 mesi fa per soddisfare alcuni requisiti, lo sviluppatore sa che è necessario porre alcune domande prima di implementare l'ultima richiesta per rendere Foo opzionale. Quando si ha a che fare con sistemi complessi, è probabile che diverse parti interessate abbiano priorità e desideri diversi. I commenti sul registro delle modifiche possono essere molto utili per documentare quali di questi compromessi sono stati fatti per evitare problemi in futuro.

Ora, se ogni sviluppatore controllasse la cronologia completa di ogni riga di codice prima di apportare qualsiasi modifica, avere questi commenti nel codice sarebbe ridondante. Ma questo è molto irrealistico sia dal punto di vista del flusso di lavoro - la maggior parte degli sviluppatori cambierebbe semplicemente la convalida senza ricercare la storia di chi l'ha aggiunta e perché - e dal punto di vista tecnologico - un sistema di controllo della versione avrebbe difficoltà a tracciare lo "stesso "riga di codice se è stata spostata da una riga all'altra o è stata rifattorizzata in una classe diversa. È molto più probabile che i commenti nel codice vengano visualizzati e, cosa ancora più importante, indurre uno sviluppatore successivo a notare che una modifica apparentemente semplice potrebbe non essere così semplice.

Detto questo, modificare i commenti del registro nel codice dovrebbe essere relativamente raro. Non sto sostenendo che i commenti del registro delle modifiche vengano aggiunti ogni volta che un po 'di codice viene refactored o quando viene corretto un bug vero. Ma se il requisito originale era "Foo è opzionale" e qualcuno arriva e cambia il requisito in "Foo è necessario per supportare la barra del processo a valle", è qualcosa per cui prenderei fortemente in considerazione l'aggiunta di un commento. Perché esiste una forte possibilità che qualche futuro utente / analista non sia a conoscenza del processo a valle e ignaro del motivo per cui Foo è stato reso necessario e chiederà di rendere Foo di nuovo facoltativo e causare mal di testa nel processo a barra.

E questo prima di considerare che le organizzazioni possono decidere di cambiare il loro sistema di controllo della versione con una certa frequenza, in particolare mentre crescono da piccole aziende con una manciata di sviluppatori a società molto più grandi. Queste migrazioni causano spesso la perdita dei commenti nel registro delle modifiche: verranno conservati solo i commenti nel codice.

— Grotta di Giustino
fonte

Esistono conversioni VCS che non conservano i messaggi di commit?

— David Thornley,

1

@ David - Ho visto molte cose che non l'hanno fatto. Non so se ci siano stati ostacoli tecnici nel fare ciò o se qualcuno abbia deciso che era più semplice "ricominciare da capo" e controllare tutto il codice per il nuovo VCS il primo giorno

— Justin Cave,

l'aggiunta di un commento che spiega perché un processo modificato può essere utile e talvolta l'aggiunta di un commento che spiega quando è cambiato, ma non vedo il merito nel mettere quel commento sotto forma di un registro delle modifiche. Per uno, nasconde in qualche modo l'utilità del commento ("Oh, è solo un commento sul registro delle modifiche") e due, incoraggia ulteriori, inutili commenti sul registro delle modifiche (rinforzo n. 1).

— Ben Hocking,

Hai smesso di usare la sorgente visiva sicura? Tutti i moderni utili sistemi di controllo del codice sorgente gestiscono correttamente i registri delle modifiche. Lo sappiamo per definizione perché se non lo facessero, non sarebbero considerati utili. Trascorri 30 minuti imparando a usare il controllo del codice sorgente che ti sarà, ti renderà molto più efficace che pregare qualcuno che sa che i tuoi strumenti ti risparmieranno delle briciole. Per non parlare del fatto che molto spesso la cronologia del codice è irrilevante, ora stai testando e scrivendo.

— ebyrob

Per quanto riguarda il "cambio del controllo del codice sorgente", quasi tutti i sistemi moderni possono spostare la cronologia l'una dall'altra, produrre singoli file di modifica a livello di progetto o con un piccolo sforzo effettivamente incorporare i loro registri delle modifiche nel file di origine (quando diventa appropriato in uno spostamento non prima). Quindi la tecnologia è lì, la gente che sceglie di non usare correttamente il controllo del codice sorgente è il problema.

— ebyrob

1

Sono sorpreso di vedere nessuno menzionato questo, ma non è il motivo originale per questo per soddisfare i requisiti di licenza? Cioè, alcune licenze dicono che qualsiasi modifica apportata al file deve essere annotata nel file stesso?

— Sverre Rabbelier
fonte

1

quali licenze lo dicono?

— Trasplazio Garzuglio,

2

Ho lavorato in un luogo in cui la conformità di Sarbanes Oxley in cui credevano richiedeva blocchi di modifica nei file di origine. Hanno anche usato PVCS (alias "Dimensions") nel corso degli anni, quindi non avevano alcun controllo di versione, ma cosa sapevo?

— Bruce Ediger,

@Marco: non ricordo o mi sarei collegato ad esso.

— Sverre Rabbelier,

1

La sezione 2a della GPLv2 lo richiede. La maggior parte dei progetti lo ignora, alcuni hanno un singolo file "ChangeLog" (spesso generato dal loro VCS).

— dsas,

0

Il motivo per cui continuiamo a mantenere un registro delle modifiche nella nostra sezione commenti è per facilità d'uso. Spesso quando si esegue il debug di un problema è più semplice scorrere all'inizio del file e leggere il registro delle modifiche piuttosto che aprire il file di controllo del codice sorgente, individuare il file al suo interno e trovare le modifiche apportate

— briddums
fonte

1

Personalmente, trovo un po 'problematico quando un file di 200 righe diventa lungo 1.000 righe a causa dell'aggiunta di un log delle modifiche in ogni file sorgente. Questo rumore extra in realtà nasconde ciò che è importante in poco tempo.

— ebyrob