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

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 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

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 5

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 6

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.