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

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.

Answer 3

I would suggest creating a method & call that from the code that is being modified.
Also, name the method to suggest the purpose/intent of the method.

e.g. GiveRebateIfValidCoupon();

Answer 4

"Any coding/commenting standards you use when modifying code?"

Yes. Make new subclasses. Leave old code alone except in the rare case that you didn't test it properly and was actually wrong.

Changes to requirements mean adding subclasses and new tests to handle the new business rules.

Answer 5

The only time I add special comments is if the modification is intended to be temporary. In that situation I flag it with a standard keyword (eg, TEMPFIX) so that I can find it later. Of course, you then have to remember to come back and remove the code or make a permanent change but on some projects we've enforced that using a macro that allowed us to specify an expiry date after which the code stops compiling.

Other than that, we rely on source control.

Answer 6

The code should conform whatever coding standards you have or your organization has.

So, No, there should not be any special comments that the code has been modified - all or at least most, code will modified sooner or later.

If there is code that you inherited that does not correspond to commenting standards, then by all means add comments as you refactor the code. If the code is really old and undocumented, naturally that means adding documentation.

It is good to understand code before you modify it (by-the-way).

Answer 7

Normally I will just change the code and make my comments in my source control check in. In the task tracking tool of choice, you can reference the revision where the task was implemented.

Sometimes I know that certain functionality is going to change back and forth, move around, change names, etc. depending on how the user requirements are debated. In this special case I will keep the old version in there and just comment it out. Then it becomes trivial to just uncomment it later, rather than slogging through source control looking for the old version. This can also save someone's ass if they have to maintain your code later, because when the users change their mind AGAIN the requirement will already be in the code, waiting to be uncommented.

Answer 8

I have to agree with a lot of other people here on SO. "If you don't need something in your code, remove it". Especially in production code, the last thing you want is a lot of clutter. It could be far easier for someone to figure out how your change works than to read your maintenance comment and possibly get confused.

I used to keep old deprecated code in my projects, but over time a project that should have only been a few thousand lines ended up being over 10,000 and hard to manage.

Answer 9

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 10

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.