I just spent an entire day worrying away at a complex bug, when a single word in a comment sparked a thought, sent me off in a different direction and solved the problem in under an hour.
Its been said before, and it’ll be forgotten again so for the record …
Comments are awesome!
The bug was in OUAnnotate, but it could have been anywhere. The problem was that when you have multiple annotations in the same place, and you click the settings button, the settings panel for the last annotation in the pile opens, not the panel for the annotation you wanted to change.
Each panel has its own object, so code like myComment.setState(‘Active’) should be very specific to the object. How could it possibly be affecting the wrong one?
It was a mess. I was seriously considering rewriting the whole state management part of the system. Yuck.
Along the way I noticed the comment “replace myComment with one for the current annotation”.
That one word clinched it. I quickly saw that myComment was in scope at too high a level, so there wasn’t one per comment, but one per location. And I could easily alter the scope by moving the definition inside the loop for each comment, and after a good amount of testing everything seems to be back to normal.
So the moral of this tale is to remember that comments can help you and those who come after you to clarify what is meant to be happening. Whenever you do something a bit fiddly, don’t forget to comment it. Especially if it relies on code elsewhere in the file/system so you can’t see the two in one place.
Oh I know code should be self-documenting. Yes that’s important too. There shouldn’t be as many comments as lines of code, and comments like $i++; // increment $i are useless.
But to those developers reading this (and me to force me to remember) anything a bit complex needs a comment. And the words need to be useful. Replace, not Set up or Declare in this instance made the world of difference.