I was reading a rather long winded comment in some source code and I started to hear the voices in my head rant about comments in code. This particular comment was written by a rather bright individual who insists on commenting his code. (To make matters worse, he uses C# regions to "hide" particularly long comments, reducing the comments value.)

Not all comments are bad. But they are generally deodorant; they cover up mistakes in the code. Each time a comment is written to explain what the code is doing, the code should be re-written to be more clean and self explanatory. If you are unsure how to make it more clear, get help .(Hopefully you were already pairing. If not, this is an excellent execuse to get another pair of eyes.)

Comments are appropriate many times. For example, comments can be used to note areas of code that need refactoring, but for practical reasons are being left as is. They may warn against changes, as a section of code may have been tweaked for performance reaons and shouldn't be changed. (Or at least the decision to change it shouldn't be made lightly.) They can note design decisions and tradeoffs made.

For example, I recently had a situation where 6 different possible actions can be invoked depending on the state of the object. This screams polymorphism to me, but I decided it would be overkill, in this case. The specifics are not relevant, but I commented the source code to indicate this decision. If someone decides to refactor it later, so be it.

So, before you use a comment for explaining complicated code, please think about a way to improve the code.