I'm not sure that asking people to document things that heavily is a good idea, because it creates a strong incentive against his latter suggestion to "Break yo

I'm not sure that asking people to document things that heavily is a good idea, because it creates a strong incentive against his latter suggestion to "Break your code into many short functions" -- you'll probably be less inclined to break out a fairly self-contained block into its own function when you know you'll have to write out yet another formal comment. And agreed, code with many short, _well-named_ functions is generally more readable than code with a few cumbersome, but heavily documented ones. Also, the places where I'm inclined to put a line comment are usually natural boundaries for extracting code into its own function.