Myths About Code Comments

theodp writes "Jason Baker gives his take on the biggest misconceptions about code comments: 1) Comments are free ('When you update the code that the comment references, you usually have to update the comment as well'). 2) Comments make code more readable ('by far the most pervasive myth that I've encountered'). 3) You should comment every function, method, class, and module ('documenting something that needs no documentation is universally a bad idea'). 4) Code must always be 'self documenting' ('would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments?')."

Comments

Re:Over documentation is good

[fdrebin]

Remember what is crystal clear to you may not be to the guy coming in to clean your mess up in a few years. ( or even yourself as you have learned more and advanced your skills, and have to go back, often with a 'wtf was i doing'.. )

I worked on the same system for 15 years. More than once I saw some code and said "what idiot wrote this!?" ... only to realize it was me, 5 years ago. Yes, that did indeed lead to me becoming a) much less prone to "clever tricks" and b) much much better at explaining what (WHY) I was doing whatever it was.

Re:Wrong on all accounts

[CAIMLAS]

What bothers me is not so much undocumented code, but undocumented functions and/or blocks of code. Main should be well documented, and a function should have a line or two explaining its function, but unless its particularly obtuse code, I don't want/need documentation.

Re:Wrong on all accounts

[Nerdfest]

.. and also, you are correct. With code that needs to be deciphered, you're generally better off re-writing it.

Re:Cliche, but true...

[BikeHelmet]

I don't clutter my code with comments. If there's a comment, it's a really important gotcha, or something that doesn't make sense but has to be left for legacy reasons.

And I write a detailed description at the top of every file. Not just what a class does, but also why. Why some of the methods do what they do, and other places they might get used that might need to be changed.

Nothing annoys me more than...

/* Method name: Foo
Returns: int Bar
*/
public int Foo()
{
return Bar;
}

When a comment could be run through a preprocessor to turn it into the actual code, the comment is saying too much, and should be removed, simplified, or changed.

Re:Less verbose is more writeable

[Ragzouken]

Your example misses the point precisely because it's just as clear in one line than in eight. You obviously shouldn't break up everything into as many lines as possible.

Re:One person's myth is another person's fact.

[JWSmythe]

    I actually did one of those comments a few days ago. There wasn't a better way to do a particular piece of code, so I put the comment in "// This is ugly, but there isn't a better way to do it.". It's a note to myself and future developers not to bother trying to fix an insignificant ugly piece.

    I do agree with the article, not everything needs to be commented. He misses out on "self commenting" where the code explains itself, so you don't need to explain it in an added comment. Intuitive variable names rather than $a $b $c are very helpful both in development, and for future maintaining.

    Sometimes things are overcommented, like the default Apache httpd.conf. I've been known to clean up such files with "mv filename filename.orig | cat filename.orig | grep -v ^# > filename", just to shorten it down to something reasonable that can be read. If you're familiar with the Apache httpd.conf, there's no need for all those comments. But, if someone needs to reference them, they're in the httpd.conf.orig.