Sunday, June 8, 2008

Literate Programming

Literate Programming
Donald Knuth. "Literate Programming (1984)" in Literate Programming. CSLI, 1992, pg. 99.

I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming."

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other.
I have always programmed like that once I started writing professionally in Forth. Leo Brodie's book Thinking FORTH [free download] was all about using the literate style. The most important thing after Naming the Parts is good factoring.


Steve Poling said...

Though I'm a huge fan of Donald Knuth, and have always tried to make my software read well, one cannot underestimate the benefits of Test-Driven Development.

First, when writing something, you should be worrying about what can go wrong. Each worry should be a distinct test.

Second, when writing tests, you have to gain access to your functionality, so you become the first user of your own interface. This forces you to create good interfaces to your functionality.

Third, when you are worrying about tests you tend to create a more "testable" design. I have a clock-radio I bought in 1973. On the main circuit board (filled with discrete components) are about a half-dozen "test points" where you could place an oscilloscope and see expected waveforms. Similarly, TDD exerts a subtle pressure upon the developer to create analogous "test points."

Finally, as people use your stuff and discover errors, you can code (should code) additional tests, one per bug, that prove your fix. And when you run all the other tests prove your fix today didn't break something that was working yesterday.

With a comprehensive suite of TDD tests, you can refactor boldly. Lacking those tests to watch your back, you are better advised to minimize the scope of any bug fixes and touch as little as possible. The result is accumulated damage to the integrity of the system. This is how software ages.

Sorry, this has nothing to do with fusion, but you did start talking about Forth and Knuth after all.

M. Simon said...

This has a lot to do wit Fusion. After all the control systems will need a lot of code.

One of the reasons I like FORTH is that tests are easy to do and to capture.

tonybarry said...

Hello Simon,
I have wondered why it is more enjoyable to write code than to read it. And I have tried to make my own code readable, perhaps even simple, because if I find it hard, how will it be for the next guy?
Steve McConnell wrote a great book called Code Complete (Microsoft Press), and it started me on the road to actually crafting code. Since then, I have read Martin Fowler's Refactoring, and Gamma et al's Design Patterns, and each gets me closer to that tantalising goal of actually writing something that doesn't have bugs! I haven't heard of theis book by Knuth (although his name is well known) so thank you Simon for bringing it to my attention.

Tony Barry