[akkartik]

Yeah, I think I understood that. My point -- at the risk of repeating myself -- is that it becomes less important to document low-level details in great gory narrative detail if calls to such functions are close to their implementations, and you can see tests that exercise them along with their callers. If you can do that, pervasive narration even seems to hit diminishing returns. I can understand what a simple function is and why it's needed just by seeing why its caller is needed, often-times.

[taeric]

Makes sense. I think your last point is why these are the harder functions to document, for me. Often they really are self evident either from their name or with their use. Trying to document them all "appropriately" often leads to more documentation than code. With neither really providing value to the other.

And, ultimately, this is why I do a "this is the boring stuff" sections. Bugs in that area should be easy and obvious to both diagnose and to fix. Bugs in the other areas are often neither.