Comments, Comments, Comments

From the title you may be guessing this is a crass attempt to get you, the poor bugger reading this, to post a comment at the bottom of this entry commending my awesomeness, but my friend it is not. Instead I thought I might briefly talk about the importance and usefulness of comments in code.

Often you hear from hardcore coders that commenting is for wimps, this sentiment comes from the same group of programmers who follow the mantra, 'If it was difficult to write, it should be difficult to read'. While these people may be justified in their beliefs, and lets face it, they do sound cool, in the long term it really isn't a good idea.

Now don't get me wrong, I am not condoning such enlightened commenting as:

                                         int val = 5; // val now equals five

This is clearly irrelevant, and only serves to de-emphasize comments that may actually be useful later on. I am talking about a brief description above a short piece of code or algorithm that briefly describes what it does. This could be as simple as //calculate shortest distance, or //rotate according to new position.

Now you could argue in these scenarios that the best idea is to create functions or methods with meaningful names such as CalculateBalance() or UpdatePosition(). This is a great idea, and often it is sufficient, but occasionally, especially while you are in the process of writing code, when you return to it, instead of having to skim through it and quickly figure out what it is doing, you can see the little comment descriptor and know exactly where you are. I have found this immensely useful when writing a method, and then when I know exactly what it is doing, I can give it a useful name so I can easily identify it.

Comments are also great for explaining your code to peers and other people who will be using your code. If you have used a certain hack or cool trick, be sure to point it out to the next guy so he doesn't have to rack his brain for why on earth you did it, remember the next guy can easily be you returning to your code a week later, finding a jumbled heap of squiggles staring back at you instead of the elegant code you thought you wrote.

Now this might be a point of contention, but I also love using comments to break up code, it makes it more readable (and more colourful if you are using lovely Visual Studio) and can make scanning through pages of code much easier.

//************************ I love comments *****************************//

void WriteComment( std::string comment );

//************************ I love comments ***************************//

You can't tell me that doesn't look lovely.

So there you go, why comments are awesome, now if only you could write a comment and have it magically turn into code, that would be sweet!