Scaling Literate Programming?

Asked 2008-11-18T15:33:48.250

Greetings. I have been looking at Literate Programming a bit now, and I do like the idea behind it: you basically write a little paper about your code and write down as much of the design decisions, the code probably surrounding the module, the inner workins of the module, assumptions and conclusions resulting from the design decisions, potential extension, all this can be written down in a nice way using tex. Granted, the first point: it is documentation. It must be kept up-to-date, but that should not be that bad, because your change should have a justification and you can write that down.

However, how does Literate Programming Scale to a larger degree? Overall, Literate Programming is still just text. Very human readable text, of course, but still text, and thus, it is hard to follow large systems. For example, I reworked large parts of my compiler to use >> and some magic to chain compile steps together, because some "x.register_follower(y); y.register_follower(z); y.register_follower(a);..." got really unwieldy, and changing that to x >> y >> z >> a made it a bit better, even though this is at its breaking point, too.

So, how does Literate Programming scale to larger systems? Does anyone try to do that?

My thought would be to use LP to specify components that communicate with each other using event streams and chain all of these together using a subset of graphviz. This would be a fairly natural extension to LP, as you can extract a documentation -- a dataflow diagram -- from the net and also generate code from it really well. What do you think of it?

-- Tetha.

methodology literate-programming

Edit Report

3 Answers

"Overall, Literate Programming is still just text"

False.

Diagrams are fine.

My thought would be to use LP to specify components that communicate with each other using event streams

That's just architecture, and that's fine.

you can extract a documentation -- a dataflow diagram -- from the net and also generate code from it really well. What do you think of it?

Data flow diagrams aren't really all that helpful for generating detailed code. They're a handy summary, not a precise source of information.

A good writing tool (like LaTex) can encode the diagram in the document. You could probably figure a way to the diagram from other parts of the documentation.

Bottom Line

In the long run, you're better off generating the diagram as a summary of the text.

Why?

Diagrams intentionally elide details. A diagram is a summary or an overview. But as a source for code, diagrams are terrible. In order to provide all the details, the diagrams become very cluttered.

But a diagrammatic summary of some other LP markup will work out fine.

answered 2010-03-31T10:38:43.663

The idea behind literate programming is emphasis on the documentation, with code sprinkled through the documentation, rather than comments sprinkled through code.

This is an essentially different philosophy, and differences like longer variable names, namespaces, and classes don't affect the philosophy. Literate programming advocates meaningful variable names.

It scales up to larger systems, because the basic ratio of documentation to code scales linearly with the size of code.

answered 2010-01-11T02:48:57.407

Try NanoLP - LP extensible tool, supports many document formats (Markdown, OpenOffice, Creole, TeX, Asciidoc and other), importing of another LP programs, templating and more. User can add own commands/macros (in Python), for example to do special importing, for example, from VCS... http://code.google.com/p/nano-lp

answered 2013-01-24T06:46:01.943

Scaling Literate Programming?

3 Answers

Your Answer