Why Literate Programming?

Several years ago, looking for an outline editor, I stumbled across Leo. I was a proponent of comments, comments, comments. I used this really cool - and long - template at the start of every subroutine. Spell out every variable, its purpose, and how it arrived (global, parameter, or local). Describe the return value in exquisite detail. Establish draconian coding standards and follow them to the letter. If everyone writes code like me, then we won't have this lump of spaghetti.

Boy was I wrong! Leo talks about this notion of literate programming. We read books all of the time. Why is so source code so much more difficult to read? What if we wrote code like a book?

Source code is fundamentally hard to read because we write it for the computer. Read the line again - I'll wait. Did you get that? Did you really, really get that? The structure of my code, the order of instructions, everything focuses on how the computer works. No wonder a human being has trouble - they're not a computer.

100 MPH in the Wrong Direction

Coding standards, comment blocks, and language constructs utterly fail at producing readable code. These solutions ignore the fundamental problem - we're trying to write the same thing for two completely different audiences. Imagine a classroom with PhD candidates and kindergartners. Now explain how to draw a landscape - to both groups - at the same time. Not a very successful lecture.

Source code faces the same dichotomy. Humans and computers simply do not think alike. Computers require very precise, very specific instructions. They have almost no attention span. And can never grasp the big picture. In short, computers are kindergartners.

A human, on the other hand, likes the big picture. We understand our world by association. How things fit together gives as much or more information as the thing itself. When one piece of code relates with another, that has meaning to us. The code that sets a verbose flag belongs with the code that prints the verbose messages.

To the computer, sequence matters. To a human, relationship matters. And quite often, these two views are diametrically opposed. Who wins? The computer. Because the computer ultimately runs the software. If it can't understand the source, then you do not achieve your goal. Human comprehension takes a back seat.

Then it breaks. Two years later, kapow! The client is screaming. You're sleep deprived. And after mopping up the mess, you think how can I avoid this every happening again. When debugging, human comprehension matters more.

All of this to say - we code for two audiences because we have two audiences.

Full Circle

Literate programming recognizes and solves this exact problem. You write and format code for a human audience. Then tell the computer how to reformat that same code for itself.

The language compiler translates English into machine codes. Literate programming tools translate human structure into computer sequence. You target both audiences, without redundancy.