My Case Against Code Comments

However, I _love_ seeing the following types of comments:

1. The high-level overview of how things fit together: 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.

2. What should work, but doesn't: 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.

3. The epic warning: 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... and so on, for a page and a half.

[I don't comment unless it's a TODO or a DONT EVER... ]

My actual argument for that style sans appeals to authority: http://stackoverflow.com/questions/499890/what-is-your-perso...

The code itself is always 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 Thou Shalt Comment mindset is responsible for most bad comments. Ignore it and only comment when it will do the reader a service.

  /** Class FooBar - The purpose of this class is to do XYZ... */
  public class FooBar { ... }

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 * / does not imply 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.