[spacemanmatt]

I want comments to give me a short-cut to reading a long block of code, and I want comments to give me a basic method of analyzing the code for correctness. The thumb-rule of documenting "why" rather than "how" seems to apply.

I shouldn't have to read code in detail to understand it, unless it is broken and I am fixing it. Comments should inform me on the broad strokes of the code.