Clojure In Small Pieces

Why bother with such a difficult method of programming? Because worthwhile programs should “live”.

Programs “live” because people maintain them. Maintaining and modifying code correctly requires that you understand why the program is written as it is, what the key ideas that make the program work, and why certain, not very obvious, pieces of code exist. Programmers almost never write this information down anywhere. Great ideas are invented, the code is written, a man page of documentation is created, and the job is done.

Well, almost. What does is mean for a program to “live”? How does a program survive once the original developers leave the project? There are many sources of information but almost no source of knowledge. New programmers don’t know what the “elders” know. In order to “live” and continue to grow there has to be a way to transmit this knowledge.

Literate programming is Knuth’s proposed idea for moving from the world of ideas to the world of information. This is not simply another documentation format. This is meant to be Literature. The ideas are presented, the implications are explored, the tradeoffs are discussed, and the code is “motivated”, like characters in a novel.

You are encouraged to write or rewrite sections of this document to improve the communication with the readers.

“But I have to learn latex!”. Well, for this document you do. But LATEX is just more than a document markup language like HTML and it is no harder to learn. It gives you the added advantage that you have a real language for publishing real documents. Most books are typeset with this technology and a lot of conferences and Journals require it. If you can learn Clojure, you can learn LATEX. If you’re a programmer you will always need to continue to learn, at least until you retire into management.