Code Craft

Practical Self-Documentation Methodologies

We’ll conclude this chapter by comparing two specific code documentation methods. Remember that these methods come after the techniques we’ve just seen. Kernighan and Plaugher said, “Don’t document bad code—rewrite it.” (Kernighan Plaugher 78)

Literate Programming

Literate programming is an extreme self-documenting code technique, conceived by the renowned computer scientist Donald Knuth. He wrote a book by this name that described it. (Knuth 92) It is a radical alternative to the traditional programming model, although some people think the literate programming episode of Knuth’s career was a large and unfortunate sidetrack. Even if it’s not the One True Way to code, there are still things we can learn ...