Comments on: Comments are evil?

By: Tseliso

Tseliso — Fri, 07 Aug 2009 06:34:41 +0000

The biggest overhead of repeating “code” is when you have to repeat the effort of maintaining the code and the repeat of the code, in this case comments.

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.

By: Svend Tofte

Svend Tofte — Wed, 08 Jul 2009 19:48:25 +0000

People seem to forget that there’s nothing like wrong comments to set you off on a wild goose chase. If the code has no comments, the comments at least cannot be wrong.

By: Basu

Basu — Sat, 06 Jun 2009 15:52:53 +0000

I’m afraid I must agree with Wynia. Just the other day I encountered a loop which started iterating over an array from 1 instead of 0 and as a result choked when interacting with client code. I changed it to start from 0 and things seemed to work from 0. The code itself was simple to understand, but I have no way to tell why it was starting from 1 or if I might have broken something else in the process. If the developer was in the habit of always commenting whys he would have paused to think about the start of 1 and written a comment about why it was there. And if it was a mistake, he would have looked over his code to see if it needed explaining and perhaps caught the mistake.
I think we should strive for the right number of comments as opposed to the fewest. It’s better to go a bit overboard than a bit under.

By: J Wynia

J Wynia — Sat, 06 Jun 2009 15:27:49 +0000

Comments are only a repetition if what you put in them is the “what”. The “what” is, indeed, already there in the form of the code. However, the “why” is often pretty much impossible to put directly into the code itself.

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.

By: 10 commandments for creating good code « Making Good Software

10 commandments for creating good code « Making Good Software — Sat, 06 Jun 2009 12:26:27 +0000

[...] 9 comments « Refactoring: The 5 main questions: Why? When? What? How? Who? Comments are evil? [...]