Is it ok to put comments about bug fixes in the so

Question

And if so, where do you draw the line? My coworkers and I disagree on this subject. I have seen such things as

// fixes bug # 22

to

// fixed bug: shouldnt be decrementing
i++;

Is it ok if the change is fairly significant, and radically changes what the method was written to do? Or do you simply change the summary text of the method to reflect what it is now meant to do?

My opinion is that this information should be put into source control. Some state that this is bad because then it will be lost outside of the context of source control (say you switch systems and want to keep historical data).

Answer 1

Something like // fixes bug # 22 is quite meaningless on its own, and requires supplementary steps to even get an idea about what it means and what role it fulfills. A short description is in my opinion more appropriate, regardless of the bug tracking or source control software you might be using.

Answer 2

My view is that comments should be relevant to the developer's intention, or highlights of 'why' surrounding the algorithm/method.

Comments shouldn't surround a fix-in-time.

Answer 3

We use Team Foundation Server for source control here at my company and it lets you tie a check-in to a bug report, so I wouldn't put a comment directly in code to server the same purpose.

However, in situations where I'm implementing code as a workaround for a bug in the .NET framework or a third-party library I like to put a the URL to the Microsoft TechNet log or website that describes the bug and its status.

Answer 4

I personally feel that comments should be about the code itself, not about a bug fix.

My reason for this is maintainability - 2 (or 10) years later, this comment will no longer be meaningful. In your example above, I would prefer something like:

// Increment i to counteract extra decrement
++i;

The difference is that it's not tied to a bug, but rather what the code is doing. Comments should be commenting on the code, not meta info, IMO.

This opinion is partially because I maintain a very old codebase - and we have lots of comments that are no longer meaningful related to bug fixes or feature enhancement requests, etc....

Answer 5

Adding a comment about bug fixing is a good idea, if you write the right thing.

For example,

/* I know this looks wrong, but originally foo was being decremented here, and 
   it caused the baz to sproing. Remember, the logic is negated by blort! */

Stuff like Fixes bug #22 is better kept in source control. Comments in your code should be signposts to help future sojourners on their way, not satisfy process and tracking.

Answer 6

We had a few comments like this, but then our Bugzilla server died and we restarted at bug #1 so they're all meaningless. A short explanation of the bug is my preferred method now.