I love readable programs. I mean: programs that you can print out, take to the park, and read from top to bottom. The reason I love readable programs is that somebody has made the effort to make them readable, perhaps simply by priting them out and running through them with a red pen a few times, and I believe this simple process to have a magical effect on a program’s clarity.

I believe that making programs readable is one of the best and easiest ways to improve them.

I gather that it used to be a common practice to print program listings and read them. I hear about it in anecdotes from programmers I respect, and I also see that many older programs appear to have been written with printing and readnig in mind: they contain pagebreak characters; they include their user-documentation in comments; and they are broken into logical sections of a couple of pages or so.

Let me share some quotations that have stuck in my memory:

The mask layout program by BillCroft at Purdue EE department - This is a truly awesome C program that could do VLSI scale designs on a PDP-11. The implementation included the command processing, high-resolution graphics, and custom database. Amazingly the program was only about half an inch thick and could be read in an afternoon. (Contrast this to my own companies’ graphics drivers for the same device which ran ten times this for the drivers alone.)

– Ward Cunningham, WardsWiki

I was the one who decided to rewrite the [program listing generator] from scratch as a standalone program, partly because I wanted to add substantial new facilities, such as the ability to list many files at once and provide inter-file cross-references.

– Guy Steele, ll1-discuss

Programming is, among other things, a kind of writing. One way to learn writing is to write, but in all other forms of writing, one also reads. We read examples - both good and bad - to facilitate learning. But how many programmers learn to write programs by reading programs? A few, but not many. And with the advent of terminals, things are getting worse, for the programmer may not even see his own program in a form suitable for reading. In the old days … programmers would while away the time by reading each others’ programs. Some even went so far as to read programs from the program library - which in those days was still a library in the old sense of the term.

– Gerald Weinberg, The Psychology of Computer Programming

How different things used to be. People measured programs in “thickness”, wrote special listing generators (in 300 pages of PDP-10 assembler - quite an effort), and dreaded that one day people may not sit down and read programs, not even their own.

I know it’s easy to feel that with our fancy IDEs we’ve advanced beyond such archaic ideas, but I believe that reading whole programs is a Good Thing and worth holding on to.

I’ve done a few experiments with readable programs over the years. The first one was about 10 years ago, a program listing generator called pbook.el. pbook itself actually sucks - it’s way too much code and way too much commentary - but regtest.erl is one reasonable example use from my professional life. I wrote another listing generator called elit.el that was intended to mimic Steele’s style with RABBIT but this program sucked too for the same reasons. I’m not sure that listing generators are really needed, at least for short programs like bets.py. Early versions of SLIME were quietly pbook-formatted and I used to read them through without mentioning it to anybody.

So why blog about this now?

I’m working on a new project called Snabb Switch. I want the Snabb Switch code to be really good, so I’m very tempted to make it readable. I’m starting to think about what could be a practical tool for generating a program listing roughly the size of a small book, with chapters like “Intel NIC device driver”, “OpenFlow forwarding engine”, and so on.

The idea I’m playing with at the moment is to have a ‘make’ target to publish the Snabb Switch on Leanpub. This way I can calmly read through my source code with a red pen on my train rides between Zurich and the Alps. I expect that this would increase the quality of my source code overall and be well worth the effort, quite independent of whether other people decide to read the program too.

I’ve at least made one pleasing discovery: thanks to the beauty of Markdown I’m now able to write a version of pbook that is down from 241 lines to a mere 43 characters: sed -E -e 's/^/ /g' -e 's/^ --- ?//g'. (See my Gist for a few more details.)

So that is my brain dump for today. Are you also interested in readable programs? Feel free to strike up a conversation with me on luke@snabb.co.