Is it ok to put comments about bug fixes in the source code?

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

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.

Answer 2

Comments should explain how the methods work.

Source control explains why changes were made.

Answer 3

Assuming comments aren't superfluous (the classic i++; //increment i example comes to mind), there is almost never a reason to argue against adding a comment, regardless of what it's related to. Information is useful. However, it's best to be descriptive and concise - don't say "fixes bug #YY", but instead add something like "this used to fail for x=0, the extra logic here prevents that". That way someone who looks at the code later can understand why a particular section is critical to proper function.

Answer 4

No. You should keep information on bugs and the change set that fixes the bug external to the source code. Any comments in the code itself should only relate to what the code is doing. Anything else is just clutter.

Answer 5

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 6

I rely on FogBugz and check-in comments in svn. Works great, though as jeffamaphone said case numbers don't make a lot of sense if you lose your bug database.

A problem with putting comments in the code is that, over time, your code will become littered with comments about problems that haven't existed for awhile. By placing such comments in the source control check-in comments you're effectively tying information about the fix to the specific version where it was corrected, which can be helpful later on.

Answer 7

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 8

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 9

I agree that such data should be placed in source control or another part Configuration Management. Having worked in codebases that place information about bug fixes in comments, I can say it leads to very cluttered comments and code later. Six months after the fix is in place, do you really want to know that about a line fixing some long-past bug? What do you do with comments when you need to refactor the code?

Answer 10

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 11

If the algorithm needs to be coded in a certain way - to workaround a bug in a 3rd party API for example, then that should be commented in the code so that the next person that comes along doesn't try to "optimise" the code (or whatever) and reintroduce a problem.

If this involves adding a comment when you fix the original bug then do it.

It will also serve as a marker so you can find the code you need to check if ever you upgrade to the next version of the API.

Answer 12

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 13

So obviously

    // fix bug #22
    i++;

is not effective communication.

Good communication is mostly common sense. Say what you mean.

    // Compensate for removeFrob() decrementing i.
    i++;

Include the bug number if it seems likely to help future readers.

    // Skipping the next flange is necessary to maintain the loop
    // invariant if the lookup fails (bug #22).
    i++;

Sometimes important conversations are recorded in your bug tracking system. Sometimes a bug leads to a key insight that changes the shape of the code.

    // Treat this as a bleet. Misnomed grotzjammers and particle
    // bleets are actually both special cases of the same
    // situation; see Anna's analysis in bug #22.
    i++;

Answer 14

In the Perl5 source repository it is common to refer to bugs, with their associated Trac number in Test files.

This makes more sense to me, because adding a test for a bug will prevent that bug from ever going unnoticed again.