I recently began a new programming project. I’m writing these programs for my own use, so I have complete control over language and methodology. I’ve been intrigued by the concept of literate programming ever since I read Donald Knuth’s book titled Literate Programming. I thought that this would be a great opportunity to give literate programming a try.

The philosophy behind literate programming is that computer programs should be written for human readability, much like a work of literature. I’m using CWEB, a literate programming tool written by Donald Knuth and Silvio Levy. I create a source file that contains both documentation (written in TeX) and source code (written in C). The CWEB terminology is descriptive: you “tangle” to create C source files and “weave” to create TeX output.

I initially found it quite difficult to wrap my mind around the literate programming approach to writing. It took a while to find my “voice” and not just mimic ordinary commenting. I think I am finally getting the hang of it and I am beginning to see the benefits.

One of the things I like best about literate programming is that it lets me structure my program the way I want. I always like to block out program logic in broad terms and then fill in the details later. Using CWEB, I can actually write my programs in exactly that way. There is a great freedom in being able to place my code where I think it belongs rather than where the C compiler requires it to be.

I also like the mental discipline imposed by literate programming. That is more difficult to describe, but it is different from the ordinary planning that always goes into programming. Everyone knows that it is fairly easy to write code that looks correct but is fundamentally flawed. I find that design errors jump out at me when I try to describe my program in a narrative form.

One example illustrates my point. I was having a lot of trouble with one section of code even though it seemed pretty simple. I couldn’t figure out why I was having such problems with it until I spotted a design error. It was a fundamental mistake and I must have recognized that it was there on some level because I kept stumbling when I tried to describe the design. Remember that if I had written that code using non-literate techniques, the code would have looked correct. I only would have found the error later on. It took some extra time now, but literate programming saved me debugging time later on.