Self Documenting Code is Not Enough

I stumbled upon an interesting article titled: Comments Are More Important Than Code. In this article, the author, Jef Raskin, writes:

Good documentation should be readable on its own, with bits of code showing how the design is implemented (and making it run, of course). Reconstructing code from good documentation is far easier than trying to create documentation given the code.

The essential concept of writing the documentation first, creating the methods in natural language, and describing the thinking behind them is a key to high-quality commercial programming.

Do not believe any programmer, manager, or salesperson who claims that code can be self-documenting or automatically documented. It ain’t so.

This reminds me of a post I wrote about a year ago: Comments Do Make a Difference. It was about a real world experience with code that was not adequately documented. I believe that good code should be self-documenting. But, I also agree with Jef that “good documentation includes background and decision information that cannot be derived from the code” no matter if it is self-documenting or not.