Rewriting Literate Programming

I spoke with quite a few people, before and around euro foo, on the subject of Literate Programming; breathless corridor conversations, a small session, continuous harking back to irc conversations with rocco. Here's the narrative comprised by my immediate notes.

True literate programming is about understanding systems, nyperlinking between their elements; being able to take a large project, and decompose it; to read the narrative of a system. Looking at parts of the system in different ways, you are highlighting intent,performing the generation of different context for each bit of code or description.

You have a sandbox, or a play toolkit, where you can mix and match nodes, code and documentation blocks.

The structure of the project becomes transparent.

In the world of aspect-oriented programming, people become excited about code metadata, about out of band attributes and relationships between code blocks. Publishing interfaces, in an RDF-like syntax, which look like pieces of a larger puzzle: "I need this, someone else should fill it in". we create descriptions of intent about the actions of things. Different annotations vary in currency and concurrency.

A term created to describe a system of very modular code blocks described, not in transliterated human language detail but at a reasoning, decision level in clear text. An environment should be designed to facilitate the writing of both code and words without bias or impediment in either. The term a trick in origin: who would want to admit to programming illiterately?

The question arises of the different aspects of "literacy" in programming, and the different problems these aspirations face. Keeping documentation and commentary "in sync" with code is a problem, and the dream goal is "self-documentation" of code writing.

A practical implementation of literate programming aims to capture the how and the why of code.

There are aspects new since the day's of Knuth's original vision: the ubiquity of the test and of test harness environments, the consensus revision control implicit in large, publically inspected open source projects.

There is a sense in which the documentation is a test, as well as a means of journalling intention. We are documenting compelx choices along with trial enactments of them.

The aim is to make of a program, a project, a living design document:something that will communicate intended and continued use patterns through its life with different participants.

Forking for introspection can make the process clearer and moreaccurate,

intent dilutes with production and adaption: this is one way to commmunicate it, that "vision and direction" so precious in the mind of project originators and idealists.

Programs which have a lot of contactwith the outside environment suffer particularly from this kind of contract dilution, Literacy at this level can be like double entry book-keeping: a statement of intent, and then a realisation of it.

At different levels of narrative - quick functional documentation, temporal blow-by-blow progress, conceptual suppositions. In documenting these microcases, we build a narrative of an implicit structure. The explanations excapsulated in a class are like linguistic contracts,

Literate programming can be a historiographic practise: "literate programming is a historic exercise". It is the archaeology of code and of the architecture implied by its designs, incurred by the impossibilities of information retrieval on sufficiently large projects.

I carry a map of how i see the world in my head.

there's more about literacy, but i don't have it written down at the moment...

20080830