Fog Creek Software
Discussion Board

Source Code Change Logs

How do you guys feel about change logs for source code files?  I've seen logs only at the module header, some logs for each routine/method.  I've also seen macros used that get recognized by source versioning systems that put the check-in, check-out comments in the source code.

The project I'm working on (over a year) has used these logs and I haven't seen a use for them.  If I want to see the history of a file, I'll browse through the comments in the source-code control system (VSS).

If a version-control system wasn't being used, I could see the value, but who doesn't use something like CVS or VSS?

Am I missing something?

Richard Childress
Wednesday, February 20, 2002

I find them pretty handy, I use them more like a running dialogue of what I am doing. Kind of like a "write-up" you did at school in a science experiment.

Matthew Lock
Thursday, February 21, 2002

You are correct! From my point ov view also, I dont see any point in using the version number header imposed by the SCM tool. Further These headers are not absolutely necessary. If you remove them, then the system will fuction in the same way as it is. But if the header is present, then the system will try to upgrade the header revision number.

I am using CVS for past 2 years, (administrative user), I have been deleting the header for the following particular reason.

We have a project which is being conducted by geographically dispersed team. For the SCM purpose , both team use CVS, But for security purpose, we use two different CVS repositories , each located at the home side of each team. And the usual practise is, a script will create a tar of whatever checked in code for a day & will send to the other location using some ecryption techniques.

The team which then receives the code, will diff the code with their version & will make sure that both the code repositories are in sync overnight. This helped us for speedy development since one team is at USA & other is at India (12 hrs gap). This helped us in 24 hr development. :-)

The main point is the diff script used to catch the header since the version numbers and the repository location was different for both the team. Which was annoying for out diff script. Removing the headers once, never needed by us to remove them again, since the system continued without headers & the diff script is also working well! The code size was over 300,000 lines of C code & almost 100,000 lines of Java code. Still we managed.

Sorry for diverting a little bit.
But main point is ,you dont absolutely require the headers imposed by the system & yes you can use the history option to see the comments ..



Thursday, February 21, 2002

I'm in favor of change logs in the source, in addition to CVS change logs.  Here's why:

1. It's really easy to look at the top of a file and see what's happened to it.

2. When you commit 15 changed files, you get to enter a single comment that described the overall change you made (i.e. "implemented new logging features").  The per-file comments can contain specifics as to what you did (i.e. "add writeSafeLog(), change closeLog() to check for current users"). 

Scott Evans
Thursday, February 21, 2002

Definitely against changelongs in the source.  These very quickly become clutter, and rarely do I care about any but the most recent changes.  If I need to know what changed between earlier versions of a file, it's mostly likely because I'm tracking down a bug that is known to exist in a particular release.  The version control/configuration management logs should have the info I need (and I'll want to diff between versions anyway, rather than trusting the comments), when I need it.  When I don't, the changelog is just so much noise at the top of a file.

I try to keep careful track of what changes I intend to check in, and do a diff before I commit anything just to be sure.  I use my notes to write terse but helpful comments to the VCS changelog.  I also favor frequent checkins with small changes, both as a way of minimizing the distance I need to back up if I really mess something up, as well as to provide a paper(less) trail of what I've been up to.

Michael Gauland
Thursday, February 21, 2002

Recently I was creating some new reports in ASP for a web-based timekeeping system we use at my work.  I had to go to existing ASP files and use them as guidelines to write my new reports.  The comments referring to the various changes made throughout the page were invaluable to me, as the code was very poor, with very similar variable names referring to very different entities.  If I did not have a record of the changes in the actual source, I would have been hating life.

And furthermore, since this was a shipped version of the product, I had no way to go and look in any type of code repository.

Nathan DeWitt
Thursday, February 21, 2002

I can see your point Nathan. In your particular case, there was no code repository to depend on.  But in the case where a VCS IS in place, like Michael said 'the changelog is just so much noise at the top of a file'

Richard Childress
Thursday, February 21, 2002

"But in the case where a VCS IS in place, like Michael said 'the changelog is just so much noise at the top of a file'."

Only if you commit your files one at a time, with specific per-file comments about each change.  And that's not generally how people work.  You modify 4 files at once, then commit them all with a blanket comment about what you did.

Having spent a lot of time in a shop with changelogs at the top of files, I never considered them "noise".  Yeah, sometimes you don't look at them, but that's why we have page-down keys. :)

Scott Evans
Thursday, February 21, 2002

Changelogs are imperative for those having to maintain code, as opposed to those originally writing code (they may be the same individuals of course).  Source control contains the actual diffs (which may or may not be available), rarely do commits give the whole context to a change, though including a reference to bug numbers should be mandatory in any Book of Rules.

In the end the code is the final documentation of the code, relying on the availability of a development environment is shortsighted.  A lot of the work I've done over time has included porting or picking up codebases where the originators have long gone and no one really knows what goes on under the hood.  Changelogs, whilst not to be relied upon absolutely are useful hints to understanding the development and the intent of the original coders.

Simon Lucy
Friday, February 22, 2002

I agree with your point for the most part.

That's why I posted, I wanted to know what others thought, about their experiences.

I've been maintaining/extending a project for well over a year now, and the change logs haven't helped me one bit.  Maybe it's because the previous developers didn't use them to their potential, I dunno.

Thanks for the input.

Richard Childress
Friday, February 22, 2002

If there's anything I hate about certain comapny policies it must be adding clutter to the source files.

Some companies require you to put a 20-something lines of lawyer-speak copyright statement on top of every header file. I once worked in a company that constantly bugged developers during code reviews, about not including (dig this) the full text of their NDA with the customer on top of every source file. I sort of began an internal quarrel, by pasting the damn text on the bottom of the file all developers thought it was a good idea and began doing it, soon management realised their effort to bust every developer's balls was futile. I mean, every single file you opened had to be scrolled to begin reading code, what a waste of brain chemestry!

I do not like SCM activity logs in my source code, I can admit, in fact I like very much, the $Id: $ tag of CVS. But that's it. What sense would the SCM make if you had the logs in your source? Would the SCM just be a backup tool to handle lines of development? I usually generate a changelog on every build, along with packaging information so people knows what they are testing, and usually all my change sets are linked to the bug/task tracking tool.

Beka Pantone
Friday, February 22, 2002

Boiler plate stuff sucks (e.g. standard function header comments). Few people at my company update these so they become increasingly silly.

The check-in comment, at least with a little bit of habituation, can get added fairly reliably. While I find that these comments are not wildly useful, they give some sense of when things change (and why), providing some context for figuring out problems.

Saturday, February 23, 2002

I think Michael Gauland got a lot of good points and I have many of the same habits.  Changelogs are an outdated concept.  Most Source Control systems allow you enter that information in at check-in time.  It can even require the developer to add the comments which is something that Changelogs don't. 

Changelogs that I've seen tend to be short and don't replace well written comments.  They don't convey a lot of information.  Finally, if your not a developer then chances are they will not be looked at. I've had build and test engineers on my teams use check-in comments when reporting problems but have not had the same experience with a Changelog.

When changes are affected over multiple files then the check-in comments on each file help piece together what has gone on and why.  With a Changelog your typically force to look at it in a one-file-at-a-time point of view.  It is much easier to use the SC interface to look at a group of files and see the comments.  When your working on a project or collection of files the power of the 'File Manger' point of view become much more apparent. 

Michael Lambert
Thursday, February 28, 2002

*  Recent Topics

*  Fog Creek Home