Chris Smith said:
There's another aspect to consider. When such a comment exists (i.e.,
this code fixes bug 27981), the piece of code is more likely to become
magic. Magic code (for those unfamiliar with the term) is code that is
there because it always has been and no one knows what would happen if
it were removed. Years later, it's often discovered that the magic code
wasn't really doing anything useful or that it became obsolete years
back; but magical code prevents change, since there's a superstition
that this piece of code can't be touched.
Far better (in an ideal world) would be to document the bug number near
the unit test, and leave the production code alone.
--
www.designacourse.com
The Easiest Way to Train Anyone... Anywhere.
Chris Smith - Lead Software Developer/Technical Trainer
MindIQ Corporation
On the other hand, it's not always magic... True story. I was doing
maintenance on an app that had been around for a long time. I found a line
in the thing that didn't seem to be executed and didn't do anything, just
loaded a register with itself. Being a conscientous programmer, I duly
commented the sucker out (we had a rule that any removed code was simply
commented out for at least 4 versions in case we had problems down the line.
Good policy.) Anyway, I recompiled that change and the ones I made and the
sucker wouldn't work. It traced it for a week. It wasn't my new code, that
was working like it should. Then I remembered the little useless line. I
uncommented that, recompiled and viola! It worked! Now I'm reallyconfused.
I look in the comment block at the beginning and see that the segment had
been written by my SENIOR DIRECTOR back at the dawn of time so I went to
talk to him. I asked if he remembered a certain program and he got this
funny smile on his face. Turns out that every programmer that ever touched
that program eventually came to talk to him about the exact problem I ran
into. The line was part of a routine in the original code but the feature
was moved elsewhere. When he deleted the routine, the rest of the thing
quit working. He added it back, and it started working again even though
that code section was never hit. A lot of time later, he narrowed it down
to just that one load register command that needed to be there and to this
day, no one knows why. I added a comment above the line "*Do not remove the
following line. Your segment won't work. We don't know why, it's just FM."