Esiste un punto per includere un "registro delle modifiche" in ogni file di codice quando si utilizza il controllo della versione?

Tendo a cancellare i commenti nel codice. E per eliminazione, intendo, con pregiudizio . A meno che un commento non spieghi perché una particolare funzione fa qualcosa, va via. Ciao ciao. Non passare.

Quindi non dovrebbe sorprendervi che anch'io cancellerei quei changelog, per lo stesso motivo.

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

Sembra che il tuo team non abbia una buona conoscenza del sistema di controllo della 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 capacità di navigare la tua fonte attraverso il web, di collegare i tuoi changeset a specifici bug, puoi fare molto per mitigare la necessità di questi 'changelog'.

Ho avuto molte persone che commentano e dico che forse ho sbagliato ad eliminare i commenti. La stragrande maggioranza del codice che ho visto è stata commentata come codice errato e i commenti hanno solo reso il problema insoddisfacente. Infatti, se mai commento codice, si può essere certi che sto chiedendo perdono dal programmatore di maintanence perché sono relativamente certo che vorranno uccidermi.

Per non pensare che io dica che i commenti devono essere eliminati per scherzo, questo invio giornaliero WTF (da un codice base I lavorato su) illustra perfettamente il mio punto di vista:

/// 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 dirti su quel codice base, e lo farei, eccetto che è ancora in uso da una delle più grandi organizzazioni governative in circolazione.

Quei "log di modifiche" incorporati nel codice sono particolarmente scadenti. Si presentano come un'ulteriore differenza quando si cambiano le revisioni, e una che non ti interessa davvero. Fidati del tuo VCS: la maggior parte ha una caratteristica di "colpa" che ti mostrerà molto rapidamente chi ha cambiato cosa.

Ovviamente la cosa davvero orribile è stata quella caratteristica dei VCS "vecchi tempi" in cui si poteva avere il registro VCS reale incorporato nei file sorgente. Ha reso la fusione quasi impossibile.

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

Non abbiamo commenti ChangeLog incorporati. Se lo facessimo, li rimuoverei e avrei un "discorso" con la persona che li aggiungeva. 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 l'accettazione dei registri. Inoltre, disabilitiamo messaggi di commit inutili o ambigui.

Personalmente detesto i log delle modifiche all'interno del codice sorgente del codice. Per me è come se violi un principio dell'ingegneria del software in quanto qualsiasi modifica che faccio deve essere fatta in più punti. Un sacco di volte le informazioni del registro delle modifiche sono completamente inutili e prive di importanza. A mio modesto parere, le modifiche al software devono essere documentate quando si controlla il codice.

Ma cosa so ...

Penso che se c'è un'insistenza nell'implementare la pratica di mantenere un log delle modifiche all'interno del codice sorgente che il log delle modifiche dovrebbe essere limitato alle modifiche che riguardano l'API / interfaccia pulica della classe. Se stai apportando modifiche all'interno della classe che non stanno andando a infrangere alcun codice che lo usi, la registrazione di queste modifiche in un registro delle modifiche è a mio avviso disordinata. Tuttavia, posso vedere come a volte può essere utile essere in grado di controllare la parte superiore del file del codice sorgente per la documentazione su eventuali modifiche che potrebbero aver infranto qualcosa per chiunque altro. Solo un riepilogo di come la modifica potrebbe influire sull'API e sul motivo per cui è stata apportata la modifica.

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

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

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

Con i commenti nel codice sorgente, la cronologia archeologica delle modifiche è stata mantenuta come note, non come codice commentato. E, sì, stanno ancora spedendo il codice VB6.

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

Se il tuo team non aggiunge commenti al check-in o lascia commenti inutili, sarà piuttosto difficile trovare le informazioni che stai cercando in futuro.

Presso la mia attuale compagnia, siamo tenuti a inviare un commento ad ogni check-in. Non solo, ma ci aspettiamo di allegare ogni assegno con un biglietto in Jira. Quando guardi in futuro in Jira, puoi vedere ogni file che è stato archiviato e quando è per quel problema insieme al commento che è 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 concordare con il modo in cui lo utilizzeranno per fornire il miglior tracciamento delle correzioni di bug e revisioni di codice pulite.

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 back-end degli anni '80).

Il tuo sospetto è del tutto corretto, questi commenti sono più di un ostacolo di un aiuto e qualsiasi VCS moderno ti consentirà di trovare esattamente quello che stai cercando. Certo, tu (ei tuoi colleghi) dovrete spendere circa. 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 giustificati solo se spiegano qualcosa che non è immediatamente visibile nel codice stesso. E ciò accade solo raramente in un buon codice. Se hai bisogno di avere molti commenti nel tuo codice, è un suo odore e grida "refactor me!".

Continuiamo a includerli nell'origine delle stored procedure perché è così che possiamo dire esattamente quale versione è presente sul client. Il resto dell'applicazione viene distribuito compilato, quindi abbiamo i numeri di versione del modulo che collegano di nuovo all'origine, ma gli SP vengono distribuiti come origine ai client per la compilazione in-the-database locale.

Il nostro codice PowerBuilder precedente li usa ancora, ma penso che sia solo un fattore di conforto per certi peep. Anche questo viene compilato per la distribuzione, quindi (IMO dovrebbero) usa la friggin VCS history.

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

SVN ha la funzione di biasimo. Questo ti dirà esattamente chi ha creato ogni linea in un determinato file e quando.

I commenti del registro delle modifiche sono eccezionalmente utili nel codice quando aiutano uno sviluppatore successivo a porre domande migliori sui 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 qualche domanda prima di implementare l'ultima richiesta per rendere Foo opzionale. Quando si hanno a che fare con sistemi complessi, è probabile che diverse parti interessate abbiano priorità e desideri diversi. I commenti del registro delle modifiche possono essere molto utili per documentare quali di questi trade-off 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 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 rintracciare lo stesso "riga di codice se è stata spostata da una riga a un'altra o è stata sottoposta a refactoring in una classe diversa. È molto più probabile che i commenti nel codice vengano visualizzati e, cosa ancora più importante, che chiedi a uno sviluppatore successivo di notare che una modifica apparentemente semplice potrebbe non essere così semplice.

Detto questo, cambiare i commenti del log nel codice dovrebbe essere relativamente raro. Non sto sostenendo che i commenti del registro delle modifiche vengano aggiunti ogni volta che un bit di codice viene refactored o quando viene risolto un bug reale. Ma se il requisito originale era "Foo is optional" e qualcuno si avvicina e cambia il requisito di "Foo è richiesto per supportare la barra del processo downstream", è qualcosa su cui prenderemo seriamente in considerazione l'idea di aggiungere un commento. Perché c'è una strong possibilità che qualche futuro utente / analista non sia consapevole del processo Bar downstream e ignaro del motivo per cui Foo è stato reso necessario e chiederà di rendere nuovamente Foo opzionale e causare mal di testa nel processo Bar.

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

Sono sorpreso di vedere nessuno menzionato, ma non è la ragione originale per cui questo è conforme ai requisiti della licenza? Cioè, alcune licenze dicono che qualsiasi modifica apportata al file deve essere annotata nel file stesso?

Il motivo per cui continuiamo a mantenere un registro delle modifiche nella nostra sezione commenti è per facilità d'uso. Spesso durante il debug di un problema è più facile scorrere fino 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