Talking about writing code, well most of the time about writing beautiful code,  "literate programming" is probably the first thing that I would have in mind.

What exactly that is? I can bet you are already familiar with Donal Knuth's research but just for a memory refresh peek a look again at http://www-cs-faculty.stanford.edu/~knuth/lp.html

In few words, the literate programming methodology gives you a way to combine a programming language with a documentation language.

But it is more than that. I think writing literate code is more about writing code for humans. Let say when you write code you'll rather have in mind your colleagues who would have to revise or to extend it later on and not necessary the server that will have to execute your code. Write everything in such a manner that any one else will understand it in an easy way. (Am I the only one telling this? And yes, I see your grin.)

Should we go a step further? Maybe the possibility to put our thoughts in the very same file (and in the very same time) with the source code we write will let us understand the whole much better. In my opinion – and probably not only – they do belong together and I wonder if there is any sense in keeping the logic of the procedures I write somewhere in a separate tool, just in my head and much better, scratch on a piece of paper in front of me?

But literate programming might be still more than everything I've storied you about it until now. Who else could explain it better than Donald Knuth himself:

“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.”

For a brief introduction, tools allowing you to write literate, examples and a couple of cool ideas see Chis Lee's “Quick Introduction to Literate Programming” at http://vasc.ri.cmu.edu/old_help/Programming/Literate/literate.html.

Next time I'll come back to you with a small riddle about tricky zapping just collected from one of the example programs on Donald Knuth's literate programming page.

Comments (4)

Subscribe to this comment's feed

Show/Hide comments

Literate Programming Continued
written by Jon Erickson, March 18, 2008

Hi Daniel,
Literate Programming is something that I should have brought up already. Thanks. Note that Dr. Dobb's has covered it in the past:


The Future of Programming
(http://www.ddj.com/184404378)

An Interview with Donald Knuth
(http://www.ddj.com/184409858)

Literate Programming in C and C++ using CWEB
(http://www.ddj.com/cpp/184403022?pgno=7)

illiterate programming
written by Chris Roeder, March 20, 2008

reminds me of a blog that irritated me for a while: http://steve-yegge.blogspot.co...-n00b.html

The author starts out arguing that more mature, better programmers don't comment as much because more is obvious to them, and then by comparing the added resolution of a strongly typed language to comments, disses them in favor of scripting languages.

I like to compare literate programming to the effect of the Cardboard Man. The Cardboard Man is probably 90% as effective as a real person when you explain the problem to him. Just by explaining the problem, you understand it better. The benefit of literate programming is that he conversation is persistent, waiting patiently for when you come back to the code months later.

Literate Programming or Software System
written by John Towell III, March 09, 2009

Daniel wrote:
Should we go a step further? Maybe the possibility to put our thoughts in the very same file (and in the very same time) with the source code we write will let us understand the whole much better. In my opinion ? and probably not only ? they do belong together and I wonder if there is any sense in keeping the logic of the procedures I write somewhere in a separate tool, just in my head and much better, scratch on a piece of paper in front of me?

Shouldn't the "logic of the procedures" you contemplate be evident in your unit-tests? The program plus the suite of unit-tests constitute the software system. Isn't the program alone, although literate, a hope untested and hence, a hack?

Test Literate!
written by Daniel Stoleru, March 09, 2009

I think I'm telling you nothing new, but Literate Programming is only a methodology combining a programming language with a documentation language. It is by now means the only one in place, but it actually is the one I do like most :-)
There is an article in DDJ written by Alberto Savoia an called "Are
you Immune to Test Infection?" (see http://www.ddj.com/architect/199902762). Well, I've got the virus and be sure I'll be the last person on this planet stopping you to do testing. Do unit testing, static testing, regression testing, you name it.
And if you want it, just combine the code in your test
units with some brief comments using the Literate Programing
methodology

Show/Hide comment form