My Case Against Code Comments

I think everybody hates comments like "getFoo: Get the value of Foo", and huge blocks of commented-out code.<p>However, I _love_ seeing the following types of comments:<p>1. The high-level overview of how things fit together: <i>This class represents a compiled method at the VM level. It does not contain the actual native code. If native code exists, it is handled using class Blah instead.</i><p>2. What should work, but doesn't: <i>You'd think the following two lines of commented-out code would work, but they don't, because libfoo 1.7.1 and earlier has a stupid bug, so we need to do things the hard way.</i><p>3. The epic warning: <i>Apple's Component Manager API does not work the way you'd naturally assume. First of all, it constructs a single 'instance' of a class before it initializes the class. Second, the memory reclamation system is really weird...</i> and so on, for a page and a half.

Summary: "Bad comments are bad. Good comments are good."

Is the "Error establishing a database connection" on your site illustrative of their mischief at work?<p>[I don't comment unless it's a TODO or a DONT EVER... ]

Nobody writes clearer code than Peter Norvig, yet he usually gives everything a line-or-so doc comment -- e.g. <a href="http://norvig.com/lispy2.html" rel="nofollow">http://norvig.com/lispy2.html</a>. That's pretty far from the comments-should-be-<i>rare</i> credo. I like it.<p>My actual argument for that style sans appeals to authority: <a href="http://stackoverflow.com/questions/499890/what-is-your-personal-approach-take-on-commenting/500268#500268" rel="nofollow">http://stackoverflow.com/questions/499890/what-is-your-perso...</a>

It's nice to see that yet one more person has come to their senses. Not much new in that post, but sometimes that's ok.<p>The code itself is <i>always</i> the first, best, and final authority on how it works. Comments should add something beyond that, or they should not be there at all. The <i></i>Thou Shalt Comment<i></i> mindset is responsible for most bad comments. Ignore it and only comment when it will do the reader a service.

Commented out code: frequently due to lack of version control, in my experience. Or one-off tests that should've been removed, but they forgot.<p><pre><code> /** Class FooBar - The purpose of this class is to do XYZ... */ public class FooBar { ... } </code></pre> &#62;<i>This is one of my favorite examples. Almost an entire line of comments wasted</i><p>Not if you use a documentation-builder. They frequently result in simple documentation turning into several lines (@param desc \n @param desc, and the like). /* * does xyz * / <i>does not imply</i> it is documenting that class and only that class. It could easily be meant for two or three classes in the same file, as they could be part of a greater whole.

I am currently getting a "Error establishing a database connection" for the page. I hope where ever that happens; there might be a comment in the code explaining why.