Maintenance commenting

Question

What special techniques you use when modifying existing code?

Eg: Say you modify a business rule inside a method. Do you mark the modified section with special comments?

Any coding/commenting standards you use when modifying code?

Answer 1

You mean something like:

foo();  // changed by SecretWiz, 20090131

I wouldn't recommend this. It clutters the code files, and the version control system should handle that for you. It keeps track of who changed what. Use

svn blame

Answer 2

If I do something like fixing a relatively obscure bug, basically anything where it isn't fairly obvious why I wrote the code the way I did, I'll typically add a comment to explain it, so that I (or someone else, if anyone else ever modified my code ;-) won't accidentally remove it later.

Answer 3

One thing I always try to do is to put in the bug ID (or feature request ID) in bug tracking system in the code checkin comments I do for that change. I add something like "see the comments for this bug/feature in bugzilla for more details". There I can and usually explain the rationale for that code change. This means that all changes or atleast all important changes need to be tracked through a feature request/bug ID. I have many times created a bug just to explain in details the business reasons involved.

Answer 4

No, that's a really bad idea. Your source control keeps a history of all edits. If you want something else, make an entry in your bug tracking tool. There's no need to comment out old sections of code or litter it with stuff like:

// modified by A.B. on 11/23/99 to fix issue #123456

I've seen comments like this in our codebase and they make no sense years down the line. Who the heck is A.B., and what was issue #123456? If the code is still here, does this mean that someone plans on rolling these changes back in the future?

These comments have no value and only serve to clutter your code.