I brought the topic of code comments up the other day at lunch to get some other's opinions about method level and class level comments, more specifically C# XML comments.  I brought the subject up because we have a policy at work to comment all methods, public and private, which I'm a bit dubious about.

It was interesting to see how widely opinions varied on the subject, from everything should be commented to produce nice CHM files to my position that comments are a last resort to explain the code to the next developer.

The best code needs no commenting at all.

public string ConcatStrings(string lhs, string rhs)
{
    return lhs + rhs;
}

That's good code.  Why?  Because I finally figured out how to join to strings together!  That may be part of it, but I deem this method pretty decent for the additional following reasons:

1. Fluent name, the method name describes exactly what the method does.
2. Short method.  The method name describes everything the method does because its small.

I think one of the best and easiest techniques to producing self documenting code is to use the extract method refactoring.  Take some code, extract a well named method out of it, and the readability goes up.

Fluent interfaces and DSL's take readable code a step further, and I think that's why they've become so popular. That, and its so damn easy to write an internal DSL in the cool popular dynamic languages like Ruby.  Why write comments buried in source code when you can write beautiful code instead? 

Have you seen developers obsessed with comments to the point of idiocy?  I know I have where I began to suspect the developer actually enjoyed writing comments more than code, or maybe writing code was too difficult for them so they focused on the low hanging fruit of comments?  Have your secretary comment your code, we as programmers should focus on writing code, good code.

Comments are not for documenting who made changes or when.  Heard of source control comments?  Heard of blame?  No?  Go learn them now.  In my experience DBA's are the worst offenders of this horrible practice, there must be something in their paranoid nature that makes them do this... obsessively.  There's absolutely no reason to litter beautiful code with code change comments, doing so only muddles the clear waters of code.

Back to my original point, I wait until I'm ready to checkin to add my comments.  In fact adding comments is one of my checkin practices.  Adding comments before then is often a waste of time.  How often have you written a method, an entire class, or even an entire namespace that never sees the light of source control?  I've mercilessly axed more JavaDoc comments and classes than I care to remember... more than I probably ever checked in.

And then the other day Jeff Atwood had a blog post about comments, and he said very concisely what I was thinking at lunch.

When you've rewritten, refactored, and rearchitected your code a dozen times to make it easy for your fellow developers to read and understand -- when you can't possibly imagine any conceivable way your code could be changed to become more straightforward and obvious -- then, and only then, should you feel compelled to add a comment explaining what your code does.

If there ever were a take away about a discussion around code comments, that's it.  Well put Jeff.

If you wait until you're happy with a piece of code, when its truly done enough to checkin you'll write less comments and better code.  Remember code comments can be a code smell.