Thanks for your comment, you indeed highlight a lot of points that make a lot of sense… Actually, I have to admit that reading again the article it does sound too extremistic, I really think you are right, there is times when a comment is necessary…

Thanks for your great feedback!!!

thanks for the interesting articles in your blog. For this article, however, I have to disagree. I think most of us all know this viewpoint from some kind of Agile-Book, but I think it’s just so plain wrong. Wynia has already said some wise words about comments. Sometimes they just can’t be let out to make the “why” clear.

There’s some other aspect I want to make clear about commenting code: At least interfaces should ALWAYS be documented thoroughly to make their contract and intention clear. It’s exactly that thing – the missing contract – that sometimes gives me a hard time, when faced with a method, used a dozen of times in the code but not working like expected. Now in that case it would have really helped to know HOW the method was expected to behave…

Another point about comments is, like Basu stated already, that they make you think about your code. Don’t underestimate that fact!

About the “out of sync”-problem: Sorry, but I think that’s really a problem that doesn’t lie in the comments but in the laziness of the developer…

As a last thing: Imagine the J2SE or J2EE libraries without their thorough documentation: Now is that crappy code? I wonder what the people of the “Comments indicate bad code”-fraction will do if they once more stumble upon a really sparse documented Open-Source-Library. In my mind I can already hear them rejoyce because they once more found a piece of software that’s so great that it doesn’t need any comments. Get my point?

Greate article about that subject from Brian Goetz: http://www.ibm.com/developerworks/java/library/j-jtp0821.html

Having code with less repeats -the same principle behind generic usable code- avoids this overhead and avoids having situations where the duplication goes out of synch.

Imagine how confusing comments that are out synch with the actual code can be.

Say you’re faced with some credit card processing code that sends all credit card numbers through validation for the CVV2 (that little number on the signature panel), but there’s this extra bit that sends American Express cards around that particular validation.

The kind of code comment you are talking about being repetitive would say something like:

//Bypassing CVV2 validation for American Express cards.

That comment clearly is redundant because code like this already makes that pretty clear:

if(creditCard.CardType == CardTypes.AmericanExpress)
{

} else
{
isValidCVV2 = creditCard.ValidateCVV2();
}

However, when you’re looking at that code, the question you have in your mind is this:

Q: Why is the code not checking the CVV2 number for American Express cards but *is* checking for the rest?

A: Because American Express wants to come on site and do audits if you check that and the product owner would rather pay the higher rate to process the cards than deal with the audit

That answer is what good comments should contain. That can mean that there are large blocks of code without comments (because the “why” is not necessary), but whenever there ARE comments, they should be explaining the “why”, not the “what”. Then, they aren’t repeating yourself.

“What” comments aren’t necessary. “Why” comments are the lifeblood of a maintainable codebase. They let you go to the people who oversee the credit card processing agreement and see if that “why” still holds true when you’re asked to dig into the credit card validation for other reasons and see if it should be left the way it is.