Ask HN: any experience with literate programming? • Hacker News Board

Post by tolini » Tue, Jan 18, 2011, 5:54 PM UTC

The concept of literate programming was invented in the 1970's by DEK with WEB [1] during the rise of structured programming. In my understanding, the goal of literate programming is to implement concepts in programs by following one's own approach, and make it understandable to other human beings.

WEB and its relatives rely on a programming language (eg. C) and a document formatting language (eg. TeX). The program and its documentation are written at the same time, in an unique source file. At anytime, one can extract the whole source files (aka 'tangling') or the documentation explaining its implementation (aka 'weaving').

Have you ever used literate programming? What is you experience with it?

[1] http://www.literateprogramming.com/knuthweb.pdf

Post by dwc » Tue, Jan 18, 2011, 6:23 PM UTC

I tried to do "true" literate programming but found the tools inadequate. Specifically, for some snippets of code I wanted to show them in more than one place in the document but that lead to all kinds of trouble. I found other things cumbersome as well. Some of that may be my inexperience, or failures of the specific tool set I chose.

Currently I use a bastardized form of literate programming that would not qualify as "real" literate programming. I put the code in the order the code belongs and I embed the document within comments in the code. This leaves the source executable for scripting languages, or directly compilable for compiled languages. We made a tool to flip the source "inside out" to produce a document (TeX/PDF,HTML).

According to LP people I am doing it wrong and not really getting the benefits. That's pretty harsh, but I've managed to live with myself somehow. What we end up with reads like a document, looks great as a web page or printed, and provides encouragement to write meaningful text descriptions. The biggest part to stress is the very last bit: writing meaningful text. Since you produce a document you expect it to read like one. This discourages stupid comments stating the obvious and encourages you to talk about reasons why and other meaningful things.

Please keep in mind that this is just my opinion, coming at LP without the benefit of working with someone who already knew it well.