[rnemo]

Agreed. While the author tends to take the viewpoint that attempting to write self documenting code is almost a bad thing, and that's very wrong, I understand his frustration, because too many programmers these days seem to think that documentation in the comments are either superfluous or a sign of bad code, and that's also just flat wrong. It's a shame that the author takes the opposite extreme.

Like most things in life, code documentation requires balance, and one should strive to create code that is easy to read and understand, but good code cannot be easy to read and understand in all circumstances, and comments should be used in any situation that confusion could possibly arise.

For my own code, aside from commenting on obviously confusing sections, I tend to create functions that have an easily understood purpose when called, but I tend to use 1-2 lines of comments when I declare the function so that I can feel reasonably sure that anyone reading my code wont have too many questions. I've found through feedback that this is a fairly functional method of documentation.