minutia press.
Literate Programming

Chris just posted about patterns. In school, it's difficult to imagine or teach their usefulness, but then in the practice of software engineering, they are much more compelling.

Over the years, when given a soapbox of the appropriate height, I've tried to preach that we should teach Literate Programming. I was first introduced to this concept by Norman Ramsey. The concept relates to third-person programming. In other words, we don't write prograams any longer for the computer alone. Running a program is not the program's ultimate function. Instead, the program can serve as a means of expression, like poetry, that must be understood by other humans. This is necessary if the program will undergo modification or reuse.

In the course of communicating to humans through a computer program, the nature of writing the program can change substantially. It no longer counts that the program does what it should, meets its specification, runs in the proper amount of time. What counts now is how long it takes another human to understand, modify, or reuse the code.

Don't get me wrong: meeting specification is important and must be taught and practiced. But the literate side of programming can be just as important to a program's success, and we don't teach this much at all.

I was given the chance in the past year to interview software engineers. I asked them for samples of their code. They were shocked. I told them that, much as an architect would carry a portfolio, they should be prepared to show and discuss code samples, software designs, bug fixes of which they were particularly proud or which demonstrated their skill.

Teaching literate programming is not easy, because it relies on close inspection of students' code, discussion with them, and iterative rewrites of the code. It's not something that most graduate students can teach yet, as they themselves may not be open to the idea of literate programming.

I know this diatribe began with patterns, but patterns are really just one way to program literately. Patterns help us describe what we are up to, and they often serve to focus one on finding a solution to a common problem.

Should we focus more on literate programming at WU?


I think that this would be a great thing to teach. I find that it takes me a long time to understand new projects that I get assigned to at work. I've been working on something for 4 months now, and I still only understand a small part of it because I have to wade through piles of convoluted code.

But I also remember in school that lots of times you're just throwing something together, making sure it works but not much else, so there might be resistence from students.

Posted by: Nathan at April 28, 2006 11:42 PM

I'd never heard the phrase "literate programming" before, but I definitely support the idea of making it a focus at Wash U. Thinking of programming as a specialized form of technical writing is really intriguing to me, and it addresses one of my existing pet-peeves: bad variable names. I think students at WU should lose points for choosing misleading or confusing names for variables in programs -- just because something doesn't matter to the compiler doesn't mean it's not important.

Posted by: michael at April 29, 2006 12:52 PM

I agree that patterns are best appreciated by programmers who have some experience extending and maintaining non-trivial programs.

Patterns can be a useful basis for communication among persons who are already conversant in the language. However, code that eschews other aids to comprehension can seem impenetrable to a novice.

I think I first heard about literate programming when I was browsing Don Knuth's web site. That's nearly the last time I heard about literate programming, also. Just yesterday I read a LaTeX macro that I guess was written in a literate style. The intent of literate programming sounded interesting, but it wasn't compelling enough for me to seek out literate code or tool support for literate development.

In the past year or so I've been using FitNesse acceptance tests at work. Our prime motivation is to communicate requirements effectively, and secondarily we want to lower the cost of testing for consistency between our software and our requirements. These tests have to understandable by end-users and programmers, so many of the tests include prose to introduce each set of assertions (fixture) and relate one to another. Some of these tests seem "literate" to me, although I'm inexpert.

I think it would be a good idea to introduce literate programming at WU.

Posted by: Sean at April 29, 2006 10:28 PM

Thanks for the pointers - I'll take a look.

Posted by: rkc at May 11, 2006 9:39 PM

Your thoughts on the teaching of literate programming reminded me of this recent article NYTimes article on how people get really good at something: http://www.nytimes.com/2006/05/07/magazine/07wwln_freak.html?ex=1147579200&en=e40757c5dcb64ce0&ei=5087%0A
It seems that the people learn the best when given direct and immediate feedback, and clear communication is a prerequisite for that.

Posted by: davido at May 12, 2006 10:26 AM