I couldn't agree more that it's very beneficial to thoroughly document your code. If you're curious, here's a snippet I wrote yesterday to tokenize a .X geometry file: http://pastebin.com/f74646d17 .... that type of aggressive source-code documentation is how I write all my code. My process is basically to write each function's entire algorithm in English, then to write the actual code. The result is "free" source code documentation. I also don't lose any productivity doing that. Just the opposite... I'm certain that it's more productive to write each function in that way, because I am constantly spotting bugs while writing the pseudocode that I otherwise wouldn't have caught until runtime. It's very easy to "misspeak" in C++. It's not a very good language for communicating concepts. But English is, and so by describing the same concept in both languages, you end up simplifying your ideas more than you would by just "speaking in one language". The result is usually a much simpler algorithm.
Unfortunately, the misconception that "writing comments makes you less productive" combined with the (valid) argument that "good code documents itself" makes this style of writing source code less than popular. But oh well, at least I can benefit from it, and maybe someone else will try it.