In "Comments Are More Important Than Code", Jef Raskin rants about why self-documenting code doesn't really exist, and what makes comments useful and informative. He was super smart, and made some good points here.

Do not believe any programmer, manager, or salesperson who claims that code can be self-documenting or automatically documented. It ain't so. Good documentation includes background and decision information that cannot be derived from the code. It is hard to imagine any foreseeable software or robot that could collect this information from the people involved with a programming project - at the very least it must understand natural language, which is still the Holy Grail to the AI community.