Experiment with Literate Programming Didn’t Work Out

About a year and a half ago, I tried doing some “literate programming” for one of our internal scripts. Well, I have just converted those scripts back to the normal, un-literate (illiterate?) style. It just wasn’t working out.

What Is Literate Programming?

The basic idea behind literate programming is that you write a free-flowing narrative, and insert chunks of code in it, like we’re doing now:

<<The most common programming example.>>=
echo 'Hello, World!';
@

 

As you can see, the chunk of code begins with <<label>>= and ends with @. A cool thing is that chunks can refer to other chunks, like this:

<<A simple PHP loop>>=
<?php
for ($i = 0; $i < 5; $i++) {
    <<The most common programming example.>>
}
@

 

As a matter of fact, this blog post is a literate program. You can run it using noweb.py -R”A simple PHP loop” input.txt and it will generate the PHP, which you can then run. (It will print Hello, World! five times.)

So What Happened?

I had a beautiful literate program to process the files received from our translators. It was fun to write – I explained what I was doing as I went along, and was able to “think out loud”, which helped with the more complicated bits. You could see the reasoning behind my choices by reading through the nearby narrative.

But the problems started happening after I was done. I was the only one maintaining the script, probably because no-one was interested in learning how to generate the PHP from it. Even for myself, it was always a bit of a chore to re-learn the proper incantation to regenerate the PHP whenever I needed to go back to fix something. And probably the worst thing about it was that when an error occurs, the line number reported by the error is for the generated file, not for the original literate file. So I would need to insert my debugging print statements in the generated file, then when I figured out the problem, make the fix in the literate file, regenerate the script, run the script, etc. A bit of a painful workflow.

How Do You “Undo” a Literate Program?

I got tired of the line-numbering mismatches and the workflow, so I made the literate program non-literate. I started with the generated script, and added back all of the narrative as normal (//) comments. It actually worked out pretty well – by rearranging the code a little bit, I was able to maintain the order of the original narrative parts. Here’s an example of a before/after:

Before:

indexOfLastMatch is simple but important. It tells us the index of the last line
matching the given regex pattern. Let's write it.

<<Finding the index of the last match>>=
private function indexOfLastMatch($lines, $regex) {
    $indexOfLastMatch = -1;
    for ($i = 0; $i < count($lines); $i++) {
        if (preg_match($regex, $lines[$i])) {
            $indexOfLastMatch = $i;
        }
    }
    return $indexOfLastMatch;
}
@

 

After:

// indexOfLastMatch is simple but important. It tells us the index of the last line
// matching the given regex pattern. Let's write it.

// [Finding the index of the last match]
private function indexOfLastMatch($lines, $regex) {
    $indexOfLastMatch = -1;
    for ($i = 0; $i < count($lines); $i++) {
        if (preg_match($regex, $lines[$i])) {
            $indexOfLastMatch = $i;
        }
    }
    return $indexOfLastMatch;
}

 

The result is definitely a different approach than JavaDoc – more of a story, a carpenter explaining his work to his hearers. I’m a fan of the JavaDoc approach (cold, systematic descriptions of each class, method, and parameter), and will continue to use that. But literate programming was a pleasant excursion into a different way of doing things. Like all vacations, though, one must eventually come back home.

Have you experimented with literate programming or ever been tempted to?

2 thoughts on “Experiment with Literate Programming Didn’t Work Out”

  1. I use literate programming quite frequently, and love it. However, you do have to account for it in your development process. In fact, I’m rewriting my blog software using literate programming this time, and I intend on (self-)publishing a book based on the results.

Comments are closed.