This well-written paper highlights the importance of thoroughly documenting code, and exposes the limitations and drawbacks of current practices like self-documenting code, automatic documentation generators, in-line comments, and so on.

Self-documenting code encourages the use of meaningful variable names, thereby marginally improving the readability of code. Documentation generators do not possess the insight of the programmer who wrote the code, and fail in capturing the finer details and nuances. In-line comments fail to achieve the desired results because of their “forced brevity,” as programmers must limit the documentation to a few lines because of constraints of the programming environment.

None of the existing practices give enough importance to proper code documentation, which, in the author’s opinion, should be very detailed, thorough, and address topics like why the program is written in a particular way, and why a specific approach is chosen when several others are available.

Good documentation should be readable on its own, with bits of code showing how the design is implemented. The author teams up with Donald Knuth, who founded literate programming (LP), to buttress his views. LP is a methodology that combines a programming language with a documentation language, thus making them more robust, portable, and maintainable. The author and Knuth advocate that programs be addressed more to humans than to computers.

Raskin further explains the need for the thorough use of internal code documentation (comments), not only for improving understandability of the code, but also for improving software quality, maintainability, and development productivity. This article is a must-read for all software professionals.