Version Control – Is a Change Log Necessary in Every Code File?

coding-standardsmaintenanceversion control

I was under the impression that a version control system eliminated the need to have "change logs" plastered everywhere in the code. I've often seen the continued use of change logs, including big long blocks at the start of stored procedures with a big section blocked out for changes to the file and littering the code with things like:

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

and:

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

The reason for this, as it was explained to me, is that it takes too long to sift through our VCS logs trying to find who changed what and why, while having it in the code file itself, either at the top or near the relevant change, makes it easy to see who changed what and when. While I see the point of that, it seems redundant and just kind of smacks of "Eh we don't really understand how to use our VCS properly, so we won't bother with that stuff at all."

What do you think? Do you use both comments and the log? Just the log? Do you find that it's easier to code when you can see above a block of code that John Smith changed the method to check for XYZ a week ago, instead of having to search through logs and compare code files in a Diff tool?

EDIT: Using SVN, but basically only as a repository. No branches, no merges, nothing except log + storage.

Best Answer

I tend to delete comments in code. And by delete, I mean, with prejudice. Unless a comment explains why a particular function does something, it goes away. Bye bye. Do not pass go.

So it shouldn't surprise you that I would also delete those changelogs, for the very same reason.

The problem with commented out code and comments that read like books is that you don't really know how relevant it is and it gives you a false sense of understanding as to what the code actually does.

It sounds like your team doesn't have good tooling around your Version control system. Since you said you're using Subversion, I'd like to point out that there's a lot of tooling that will help you manage your subversion repository. From the ability to navigate your source through the web, to linking your changesets to specific bugs, you can do a lot that mitigates the need for these 'changelogs'.

I've had plenty of people comment and say that perhaps I'm in error for deleting comments. The vast majority of code I've seen that's been commented has been bad code, and the comments have only obsfucated the problem. In fact, if I ever comment code, you can be assured that I'm asking for forgiveness from the maintanence programmer because I'm relatively certain they'll want to kill me.

But lest you think I say that comments should be deleted in jest, this Daily WTF submission (from a codebase I worked on) illustrates my point perfectly:

/// 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... The stories I could tell you about that codebase, and I would, except that it's still in use by one of the largest government organizations around.

Related Topic