Rethinking Old Habits: The Comment Header Block

Old habits die hard, but occasionally it is good to look at them and see if they still make sense...  When I started writing code, many moons ago, it was ingrained into my work habit to create or update a comment block at the top of the code file.  This may be a foreign concept to some of you, so let me describe it.  Typically this would include information about who was the original author, date it was created, a description of the purpose of the code, and a change log.  The Change Log part of the comment block is where developers would enter their name or initials, the date of the change, and a description of what the change was that they were making.  Sometimes it would have a reference number to cross reference their changes to a bug-tracking system.  This comment block would appear at the top of any type of code file, whether a SQL Script, a web page, or source components that were eventually compiled into DLLs and the like.

Fast-Forward to today where much has changed.  All the world seems to want to be faster and more Agile.  We have tools that tell us more about our source code than ever before.  For example, in our office, we use SourceGear Fortress as a big part of our ALM process.  With Fortress, I of course have my source code history and can easily run a Diff to see what changes were made between two versions, and by whom, based on who did the check-in.  Also, we require linking all code check-ins to an item in the item tracking side of Fortress, so I can easily look up the details of the bug or enhancement that led to the change.  Conveniently, I can also see a list of all the source code files that were changed for that item.

So, the question arises, with all that the Fortress tool is doing for us, is the comment header block, or at least the Change Log portion of it, of any value anymore?  I could see where you might still want the description for the file, but when it comes to your .NET code, maybe just the comments in front of each routine are sufficient (although some argue that you should do away with those, too).

Maybe I'm just slow to the party to rethink this one, but I'm curious what others think about it, especially those of you who have, or at one time had, this habit too.

posted @ Tuesday, April 08, 2008 11:29 PM


Comments on this entry:

# re: Rethinking Old Habits: The Comment Header Block

Left by Mladen at 4/9/2008 4:14 AM
we use source off site and when anyone does a check in he has to provide a comment that is writtem to the top of the file.
works great for us, since you only have to look at the comment to see what area was modofied. you can still do file diff for exact changes.
is that what you mean?

and frankly the comment "code should speak for itself" that some make is pure BS. the comments are supposed to tell you the intent of the programmer in simple words. you can scan the code quicker IMO.
Comments have been closed on this topic.