

Ask HN: any experience with literate programming? - tolini

The concept of <i>literate programming</i> was invented in the 1970's by DEK with WEB [1] during the rise of <i>structured programming</i>. 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.<p>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').<p>Have you ever used literate programming? What is you experience with
it?<p>[1] http://www.literateprogramming.com/knuthweb.pdf
======
dwc
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.

