While discussing some released code recently with a colleague, I remembered a little “rule”.
We were talking with a customer who was giving us feedback about what appeared to be a bug. The developer looked up the related code and discovered comments in the code that described why it was done the way it was done. Essentially, the customer was reminded that it was working as previously requested.
However, this reminded me of an opinion I have about both comments in code and capturing requirements. I believe that comments in code are useless. There are exceptions of course. The problem with comments are that they aren’t part of the code stream and there’s nothing to control that they are correct. Comments can even be misleading.
Reminds me of that old joke of the lab assistant at college helping new programming students getting their assignments correct. The lab assistant was asked to help a student and that student remarked, “You know, I get the idea that the compiler is completely ignoring my comments.”
So what about the situation where the “reason” for some code was captured in comments?
My recommendation is to capture your requirements in a unit test. Get rid of the comment. Make a unit test that demonstrates the setup and expected results in such a clear manner that it’s obvious what the requirement was.