| I think everybody hates comments like "getFoo: Get the value of Foo", and huge blocks of commented-out code. 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. |
* Or if you're not into the whole imperative languages bit, what things are done.