In response to this recent post on The Daily WTF, I’d first like to point to the second last entry on The Klingon Programmer’s Code of Honour. But this post is more than a lame attempt to get my blog associated with the word “Klingon”.
When it comes to comments I actually have the opinion that less is more and I despise those educational institutions and coding guidelines which dictate the use of verbose commenting. Now I am not talking comments in the form of good code structure, I’m talking about the wall of green can often be described as a code smell.
Comments aren’t bad, they are just often mis-used, for example if you are using a low level API where the function calls really don’t describe what is going on, then a quick comment can be helpful, but seperating that chunk of code out into a method by itself would serve exactly the same purpose and at the same time contribute descriptive to the call stack in the event of an error.
So there you have it, light comments aren’t just good coding style – its good from a maintainability point of view. Now that I have put the cat amongst the pigeons let me step back a bit and acknowledge that there are always exceptions. For example, demo code is great when it has comments, especially if you are unfamiliar with most of the frameworks that are being used, but my advice is simply this – when you are compelled to enter a comment, stop, and think if there is a better way to describe this to the maintainence programmer.