h2g2 The Hitchhiker's Guide to the Galaxy: Earth Edition

Some people (me and my mate Bill, for a start) think it is a good idea to try not to use comments. Or rather, to try not to NEED comments.

Write you code so clearly, with such explicit communication, that most comments become unneccessary.

For example, if you had a comment saying:

"Now calculate the sum of the ages of all the children on the third donkey"

followed by 6 lines of code that did that, replace this block of code with a call to a method:

sumAgesOfChildrenOnDonkey(3)

and put those 6 lines in this method. No comments are required - the method name says it all - and so you won't suffer from out-of-date comments or comments that come adrift from the code they are referring to (strange how often that happens!). Your code is also magically much more readable.

There are many other techniques like this to make your code self-commenting - see the works of Martin Fowler ("Refactoring") an Kent Beck ("Extreme Programming Explained"). Eventually you might find that you have tidied up and rationalised you code as much as you can and you STILL need a comment - often, because you want to explain not what is being done but why it is being done. Then by all means write the comment, and feel in addition the warm glow that you have more readable (and reusable) code thrown in as a side-effect of your effort not to need the comment.

I suppose, in summary, I'm suggesting that we make sure we are not using comments as a shortcut to clarity because we are too lazy to make the code as crystal clear as it could be.

This is true, but a comment can also be a refernce to the design document/specification that lead on to the code involved and so on.

The new IDE for C# and Vb.NET has a nice feature - the "Region" comment which allows you to wrap up a region of code with its comment and in the IDE it displays the result as a collapsible/expandible block - which allows you to go from high level overview to source code and back again easily.

Not sure I'd agree with that...

I used to be a pretty gung-ho kind of programmer. At first I thought comments were just plain stupid ("why put in a line that the computer isn't going to execute?"). Then at college I HAD to put comments in to my code to make life easier for the lecturer. Fair enough, I supposed, because he has got an awful lot of code to mark.

When I started working as a programmer I had "evolved" to thinking that comments were for sissies, or for turkeys who couldn't read the code and so had no business TRYING to read it.

Until I had to re-visit some of my own work 6 months later and found myself thinking "I KNOW I had a good reason for doing that, but I'm blowed if I know what it was".

I started coming around to the idea that perhaps comments were a good thing because they explained thought patterns, explained the reasons for doing things a certain way.

I do think it true that a good programmer should be able to decipher code - no matter how poorly it is written. I've done that often enough myself. But from a business point of view, if I give one of my programmers some code and say "change it to so the flow gate arrays are stripped into virtual message elements", I want them to be able to spend their time on designing the change properly, implementing the change and then debugging; I DON'T want them to have to spend two hours figuring out what the code is doing.

What I've come to believe is that writing a program is not a matter of communicating with a computer, it's a matter of communicating with the programmer who locks up at your code at a later stage.

Well chosen variable and routine names are important and do help to make a program more easily understood, but good comments really make it easy for others to understand the code.

Here's another take on comments. There's a school of thought that says that you should write the comments FIRST and then fill in the code after the appropriate comments. The reason - and it's not something to discount out of hand - is that if you can't do it this way then either you haven't understood the requirement, or your solution is ill-defined. In this case the comments tell the programmer if s/he has understood what s/he is trying to do.

True - but the original poster's point is that comments that are not maintained when the code is maintained are harmful.
The reasoned response is that you need to force people to update the comments as well as the code, and this must be policed as part of a comprehensive code review policy if you want high quality code.

A related rule which I should have included is "Never comment out a piece of code" because what happens is that when another developer comes across a section of commented out code when investigating a fix their instinct is to re-include the commented out code to see if that fixes the problem. 99% of the time that just makes things worse.

Point taken. Yes, comments DO have to be maintained along with the code.