Comments are for the weak.

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.

About these ads

One thought on “Comments are for the weak.

  1. Sean Malloy

    an example…

    if ((flags & 1000) == 1) // am I visible

    {

    }

    what a useful comment! But, couldn’t it be better written like so:

    bool isVisible()

    {

    return (flags & 1000) == 1;

    }

    if (isVisible())

    {

    //no more redundant comment

    }

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s