Developer Change Log in Source Management or File?

We’ve got Source Code Management and life is good (as far as people’s work not colliding with others etc.). However, we have some people who insist on commenting their changes *in the source file itself* instead of in the “Comments” block of the “Check In” dialog.

Example:
/*******************************************
*Program Name: FooBar.c
*    Written: 01-JAN-2047 by Joe Coder
*    Purpose: Generates some magic given pixie dust.
*
*    Modified: 02-JAN-2047 by ABC – Forgot to add magic. Added it.
*    Modified: 03-JAN-2047 by GEF – Fixed radiation leak at line #431,675,123.
*
*        NOTE: Don’t run this program on a Friday or it will cause a singularity.
*******************************************/

Sometimes there are even commented-out blocks (which we all agreed earlier is a BadThing(TM)) with comments at the point, e.g.:
// 10-JAN-3044 by PAS
// Removed cancer-causing gene. Why did we ever put this in here?
// human_genome.add( “Cancer” );

Personally, I’d rather look at the file history in the SCM program instead of opening up the file and looking at potentially misleading comments. For example, the SCM program “knows all” and I can easily get the *exact* changes made to the source. The header version can easily become out of date if you forget to document what you’ve done or make major changes (removing other bugfixes etc.).

But, some people say that it’s nice to have the changelog independent of the SCM program (say if you are given the source itself). To this I say: "Fooie!" – how often would it be that you need to see the changes but don’t have access to the SCM?

Some might say that the functional specifications should be the place where this is kept (since new functionality needs to be documented somewhere), and I would be inclined to agree – but it would require that we write such documents (another story for another day) and that is out of the scope of this mini-poll.

So, a little impromptu poll: Do you think source modification comments should be made in the source file, the SCM provider history log, both, or neither? Explain. (I sound like one of my old professors!)

MR
Thursday, May 27, 2004

Oh, also one point I just thought of for documenting in the file:
When you check in a file typically you've made several changes -- so your Check-In comments might not be wholly accurate either.

In any case, I think the final answer is to use the SCM diff tool to *really* see what changes were made and only use the comments (either SCM or file-level) as a rough guide.

MR
Thursday, May 27, 2004

As much as I love replying to myself, a slight clarification:
When you check in a file typically you've made several changes >over an extended period of time< -- so your Check-In comments might not be wholly accurate either >because you may have forgotten exactly what you did two days ago<.

MR
Thursday, May 27, 2004

Having all comments in the check-in block is all well and good, but what happens if you decide to change source control software?  Unless your current system lets you export all the comments somehow you lose all the comments.  That would make life tough when you need to figure out why Joe Bloggs made the change that he did and unless you work in a rigorous dev dept then your design specs are probably not going to be good enough either.

On the other hand a friend of mine once worked in a dev shop where the policy was to have no comments in the code at all (including the dreaded commented out block) and that all code should be of a high enough standard to be self documenting.  The idea was that comments invariable get out of date quickly and eventually just confuse programmers further down the line when they have to work what they mean.

Not Waving But Drowning
Thursday, May 27, 2004

Delete the comments by hand. Then add a tool to
delete the comments. They don't belong in the
file.

son of parnas
Thursday, May 27, 2004

At my first job, the "coding standard" was to put the change comments in the source file.  There was even a debate as to whether these comments belonged at the top or at the bottom.  We eventually moved away from this, and here are the reasons:

1.  Excessive comments in the source tend to obfuscate rather than clarify.  After 100's revisions of a file, the majority of the file becomes comments.

2.  Revision information is really only meaningful in the context of the revision management software.  When I am looking at code, knowing what changes were made 100 revisions ago just don't matter to me.  If I am tracking down a bug and am trying to see what changed from version to version, then I might care, but I probably will also be using the revision management software to see the old code, so it isn't a big deal to also use it to see the comments.

3. Without serious group discipline on the subject, it is likely  that the majority of these comments will be useless anyway.  "Fixed a bug."  or "Added Feature X" (comment duplicated in 50 source files checked in at the same time.  Putting this in the revision management software rather than source at least reduces the amount of meaningless comments in the code.

madking
Thursday, May 27, 2004

Quote:

"3. Without serious group discipline on the subject, it is likely  that the majority of these comments will be useless anyway.  "Fixed a bug."  or "Added Feature X" (comment duplicated in 50 source files checked in at the same time.  Putting this in the revision management software rather than source at least reduces the amount of meaningless comments in the code."

What we do is start the log message of with "Bug: XXXX". Then, 70% of the comments have more clarifications in the logmessage. The other 30% only has this bug ID to go with it. Then anyone can lookup that bug in the bugtracking system. Ofcourse, this add's an extra dependency (but if we lost our bugtracking system we would be in deep **** anyway) but it provides an easy and quick way for developers to say what they just did.

(Oh, and always make sure you check in one change at a time!)

Jilles Oldenbeuving
Thursday, May 27, 2004

Firstly, I really don't think you should check in a file having made several changes over an extended period of time. You should try to make each file revision contain an atomic change, preferably task based, so each change can be separately seen, understood, and rolled back if necessary.

Secondly, putting a comment in the revision header at the top of a file for each change has one golden advantage: If you diff two file versions, the difference in the revision headers gives an immediate and obvious summary of what changes were made between the revisions.

Scanning differences in revision headers like this is much quicker than comparing source code differences deep in the file and trying to separate which difference relates to which fix, and trying to deduce the functional aim of each change. Especially if I am not an expert on that particular file that I am diffing (e.g. it might be a GUI file and my expertise lies in another part of the system).

Ian
Thursday, May 27, 2004

Most SC tools have macro expansion that will automatically add the change info to the file (synchronizing source control and the file). For example $history in VSS.

Dennis Forbes
Thursday, May 27, 2004

In CVS $log$ will expand the commit comments. I am sure other SCMs do the same. You should probably have a standard documentation style in your code...look into doxygen

Tom Vu
Thursday, May 27, 2004

Whilst it might be nice to atomically check in all changes reality tends to obtrude.  If you're refactoring you'll probably need to make a host of changes in one place, that's a single checkin, and a checkin only after its past basic testing.  A single comment on the checkin of 'Oh I refactored X' is going to be pretty meaningless.  On the other hand a comment such as 'refactoring X re bug #898898.  Is going to be documented properly.

I used to be a great fan and user of history logs at the beginning of source files.  However, lots of languages and IDE's now make that trickier because the source doesn't live in files in quite the same way.

A way round that is to add a property 'Comments'  if it doesn't already exist and use that, but the problem with structured IDE's and OO snippets is that its easy to miss a particular tree in the wood.

But my personal choice is to have a meaningful checkin comment tying it to a bug number.

Simon Lucy
Friday, May 28, 2004

> Fooie!" – how often would it be that you need to see the changes but don’t have access to the SCM?

Very often?

It all depends on what code you write, and what constitutes your final product.

I frequently debug run-time libraries while on-site at a cutomer, and I do not have access to the SCM or the build system. All I have is sources (on my laptop) and release build on the customer machine. Having change log in the sources helps. Sometimes it helps a lot!

Employed Russian
Friday, May 28, 2004

Are you kidding? This shouldn't even be a question. Developer comments in the source code, along with a standardized change log in the header or at the stop of the source file are an INVALUABLE piece of history for any programmer who has to work on the code.

Why on earth would I want to have to go pull the comments out of the SCM when I can have the change log and comments right in-line with the code I'm looking at?

What happens when you change SCM? Hopefully the comments convert over at 100%, with no loss of history. If the developer comments are not included with the source code, it's like reading a book or an article without understanding the context for it.

This is a no-brainer both from a management and programmer perspective. Comments included with the source code give accurate history and proper context for future developers to understand WHY the code looks the way it does.

Tom Anderson
Monday, June 28, 2004

I prefer the principle of commenting each line of code (well at least enough that people can understand what you've done).

Then adding change comments via SCM. That's what SCM is for - tracking changes.

Yes, I can use the History tag with the SCM to have it squirt in all the changes into the file, but then its clogging up the file when i already have it somewhere else.

I agree that converting SCM's would be a problem.
Patient: doc, it hurts when I move my arm like this
Doctor: don't do that.

Net Effect:
comment lines of code so people can read your code
comment changes via SCM.

eAndy
Monday, June 28, 2004

  Recent Topics

  Fog Creek Home