Literate programming: presenting code in human order

Peter Norvig's comment hits the nail on the head for me:

" Peter Norvig 6 July 2016 at 11:47 I think the problem with Literate Programming is that assumes there is a single best order of presentation of the explanation. I agree that the order imposed by the compiler is not always best, but different readers have different purposes. You don’t read documentation like a novel, cover to cover. You read the parts that you need for the task(s) you want to do now. What would be ideal is a tool to help construct such paths for each reader, just-in-time; not a tool that makes the author choose a single pth for all readers."

Has anyone attempted something like this?

I've heard you can do transclusion in org-mode which might be a starting point

Edit: Some initial ideas:

- Code can be deconstructed into blocks, and where the code is not self-documenting, prose can be added. Or even visualisations etc if a block is conceptually tricky to grok. You could even have MOOC-style validations to verify reader understanding for each block.

- Some kind of topology of the blocks should be generated based on how they interact and how they are conceptually related

- The author creates a few 'starting points' for different audiences, e.g. 'if you've used X before, start at Y'

- From there next blocks to read are auto-suggested to the user. A map or network diagram of all blocks is also provided so the reader can chart their progress and see where the 'big ideas' lie.

Edit 2: This also really reminds me of Bret Victor's 'Humane Representation of Thought' lecture (https://vimeo.com/115154289, 45:40) where he says there is a conflict between code being an engineering specification and an authored work meant to be read by humans.

Literate programming is a thing that's long piqued my interest, but it usually seems more suited to academic or personal use.

Having said that, a beautiful example of LP in the wild is geom[0], a Clojure/Clojurescript library written entirely in org-mode. Browsing through the source, I have to keep reminding myself that I'm looking at the code and not just the documentation.

[0] https://github.com/thi-ng/geom

It would help if editors stopped treating comments as second-class content. Most atom themes, for example, render it as I would render unused code (if I were to commit such atrocities) – grey on (light|dark) grey.

I wish there were a functioning plugin to render markdown inline. I bet people would start caring about comments just because they looked better.

Language or "human order" is pretty cumbersome to express ideas. It is full of double meanings, assumption and expectations.

Any attempt to express complicated and precise ideas in natural language results in hard to understand gibberish. And you will need special training to decipher it anyway. Law is good example.

I think programming languages as we have them are good for instructing computers.

My latest attempt at this problem is a tool I call `cq` [1]. It's a way to query code with a selector, rather than line numbers. I use it for blog posts to pull code chunks into markdown.

It lets you write a (static) document that mixes prose and code in a way thats best for the reader. But 1. the code is runnable on disk and 2. you don't have to copy and paste.

Generally I find that literate programming solutions don't have good support for hiding portions of the code. This tends to limit the tool's applicability to trivial code examples.

I use `cq` to extract key code blocks from complete projects and then provide the whole project alongside the post.

[1]: https://github.com/fullstackio/cq

It seems to me that well-documented code should follow some sort of power law:

Each line should be documented (best if self-documented).

Each function (of around 10 lines) should be documented.

Each group of functions (of around 100 lines total) - approximately a class - should be documented.

Each module (of around 1000 lines) should be documented.

.. etc. up to the final documentation about the whole program.

Each level of documentation should summarize the purpose, inputs, outputs, assumptions and architecture of the thing being described. So a higher level should be around 10x smaller part of the total documentation (of course, some other factor could be used).

There was a fantastic set of panel discussions at MIT on dynamic languages in 2001. In the Q&A period of the panel on runtime [1] Guy Steele asked the panel what they thought about literate programming [2], and some good discussion ensued. Some points made that I particularly liked were the point that people generally don't even make the effort to keep comments up-to-date, much less writing them well in the first place, never mind thinking about a good order for the human to read them in.

[1] https://www.youtube.com/watch?v=4LG-RtcSYUQ

[2] https://www.youtube.com/watch?v=4LG-RtcSYUQ#t=1h21m43s (discussion lasts about five minutes, participants include David Moon, Scott McKay, and Guy Steele)

Org mode is very good, if not the best, way to do literate programming. My blog post about it: https://kozikow.com/2016/05/21/very-powerful-data-analysis-e.... I use it at work for data analysis and "researchy" projects.

Many of my blog posts at kozikow.com are written in the literate programming style in org mode, and you can see the org files at https://github.com/kozikow/kozikow-blog.

People have written whole books in it: https://github.com/jkitchin/pycse.

The first comment, written by none other than Peter Norvig, is also worth reading.

EDIT: link - http://www.johndcook.com/blog/2016/07/06/literate-programmin...

We have tools that let you examine code from various angles. There is no need to encode some "human order" in the code itself. Code should be organized in the way that harmonizes with the module structure and promotes maintainability, without regard for some "human order" nonsense.

Who decides what is "human order"? Humans want things in different order for different purposes. For example, business software generates all sorts of reports of different kinds from the same data.

This is wrong:

> Traditional source code, no matter how heavily commented, is presented in the order dictated by the compiler.

This is only true of one-pass, strict definition-before-use, single-module-only programming languages, like toy versions of Pascal.

In any decent language, we can take exactly the same program, and permute the order of its elements with a great deal of liberty, and present them in that order to the compiler. We can decide which functions go into which modules, and we can have those functions in different orders regardless of what calls what.

Ah, but some of the more crazy proponents of literate programming are not satisfied with that granularity. It bothers them that the individual statements of a program that are to be executed in sequence have to be presented to the compiler in that sequence: S1 ; S2.

Knuth's outlandish version, in particular, stretches the meaning of "literate" by turning code into a dog's breakfast in which functions are chopped into blocks. For compilation, these blocks are re-assembled by the "literate" processor into functions.

The result is difficult to understand. Yes, the nice explanations and presentation order may present something which makes sense. But here is the rub: I don't just want to follow the presentation of a program, I want to understand it for myself and convince myself that it is correct. For that, I need to ignore all the text, which, for all I know, only expresses the author's wishful belief about the code.

I understood the concept of literate programming of a way to organize _source code_ in such a way that it 'flows' better for a human, i.e. it starts with the methods/functions/modules/blocks where you naturally would start if you were to explain your code and then on to the next method/function/module/block that you would explain. Perhaps some comments here and there to explain where to start and what are special points of interest. I should have read the wikipedia article I suppose where it seems to be actual prose... :) Now I am not sure I like the idea - always found well-written source code to be easier maintainable and understandable than prose...

The problem with most programming languages is that programmers write programs in it by incrementally adding to the code in random places.

I think we need a programming language that allows programmers to build programs by merely adding things to the bottom of the source file.

The best way to document a program is to prove its correctness. Short of that, it is usually no fun to deal with other peoples (or your own old ones) programs anyway.

As for presenting things in the right order: This order would largely be imposed by a correctness proof. As there could be different proofs, there could be different orders.

Obviously, not all programs can be proven correct (but I think a very large part of all programs could be). Also, finding the right order is not as difficult as finding the right level of abstraction. Once you have the right level of abstraction for presenting something, everything else flows from that.

I wrote this before, a previous time the subject came up. people seemed to find it useful then, so maybe they will now as well:

A previous employer (a subdivision of a global top ten defence company) used literate programming.

The project I worked on was a decade-long piece for a consortium of defence departments from various countries. We wrote in objective-C, targeting Windows and Linux. All code was written in a noweb-style markup, such that a top level of a code section would look something like this:

    <<Initialise hardware>>
    <<Establish networking>>

and so on, and each of those variously break out into smaller chunks

    <<Fetch next data packet>>
    <<Decode data packet>>
    <<Store information from data packet>>
    <<Create new message based on new information>>

The layout of the chunks often ended up matching functions in the source code and other such code constructs, but that wasn't by design; the intention of the chunks was to tell a sensible story of design for the human to understand. Some groups of chunks would get commentary, discussing at a high level the design that they were meeting.

Ultimately, the actual code of a bottom-level chunk would be written with accompanying text commentary. Commentary, though, not like the kind of comments you put inside the code. These were sections of proper prose going above each chunk (at the bottom level, chunks were pretty small and modular). They would be more a discussion of the purpose of this section of the code, with some design (and sometimes diagrams) bundled with it. When the text was munged, a beautiful pdf document containing all the code and all the commentary laid out in a sensible order was created for humans to read, and the source code was also created for the compiler to eat. The only time anyone looked directly at the source code was to check that the munging was working properly, and when debugging; there was no point working directly on a source code file, of course, because the next time you munged the literate text the source code would be newly written from that.

It worked. It worked well. But it demanded discipline. Code reviews were essential (and mandatory), but every code review was thus as much a design review as a code review, and the text and diagrams were being reviewed as much as the design; it wasn't enough to just write good code - the text had to make it easy for someone fresh to it to understand the design and layout of the code.

The chunks helped a lot. If you had a chunk you'd called <<Initialise hardware>>, that's all you'd put in it. There was no sneaking not-quite-relevant code in. The top-level design was easy to see in how the chunks were laid out. If you found that you couldn't quite fit what was needed into something, the design needed revisiting.

It forced us to keep things clean, modular and simple. It meant doing everything took longer the first time, but at the point of actually writing the code, the coder had a really good picture of exactly what it had to do and exactly where it fitted in to the grander scheme. There was little revisiting or rewriting, and usually the first version written was the last version written. It also made debugging a lot easier.

Over the four years I was working there, we made a number of deliveries to the customers for testing and integration, and as I recall they never found a single bug (which is not to say it was bug free, but they never did anything with it that we hadn't planned for and tested). The testing was likewise very solid and very thorough (tests were rightly based on the requirements and the interfaces as designed), but I like to think that the literate programming style enforced a high quality of code (and it certainly meant that the code did meet the design, which did meet the requirements).

Of course, we did have the massive advantage that the requirements were set clearly, in advance, and if they changed it was slowly and with plenty of warning. If you've not worked with requirements like that, you might be surprised just how solid you can make the code when you know before touching the keyboard for the first time exactly what the finished product is meant to do.

Why don't I see it elsewhere? I suspect lots of people have simply never considered coding in a literate style - never knew it existed.

If forces a change to how a lot of people code. Big design, up front. Many projects, especially small projects (by which I mean less than a year from initial ideas to having something in the hands of customers) in which the final product simply isn't known in advance (and thus any design is expected to change, a lot, quickly) are probably not suited - the extra drag literate programming would put on it would lengthen the time of iterative periods.

It required a lot of discipline, at lots of levels. It goes against the still popular narrative of some genius coder banging out something as fast as he can think it. Every change beyond the trivial has to be reviewed, and reviewed properly. All our reviews were done on the printed PDFs, marked up with pen. Front sheets stapled to them, listing code comments which the coder either dealt with or, in discussion, they agreed with the reviewer that the comment would be withdrawn. A really good days' work might be a half-dozen code reviews for some other coders, and touching your own keyboard only to print out the PDFs. Programmers who gathered a reputation for doing really good thorough reviews with good comments and the ability to critique people's code without offending anyone's precious sensibilities (we've all met them; people who seem to lose their sense of objectivity completely when it comes to their own code) were in demand, and it was a valued and recognised skill (being an ace at code reviews should be something we all want to put on our CVs, but I suspect a lot of employers basically never see it there) - I have definitely worked in some places in which, if a coder isn't typing, they're seen as not working, so management would have to be properly on board. I don't think literate programming is incompatible with the original agile manifesto, but I think it wouldn't survive in what that seems to have turned into.

Regarding the tangle barrier issue, there is a tool that helps: https://github.com/aryx/syncweb It allows to modify both the original WEB document and code and keep them in sync.

I am a fan of the literate programming style for personal projects.

For a very well executed and interactive example check out

http://dave.kinkead.com.au/modelling-the-boundary-problem/

My main problem with literate programming is that it is difficult enough to keep short comments up to date vis-a-vis the code they describe. Longer comments would be even worse.

I also suppose the modern equivalent of this, in many use cases, is a Jupyter notebook.

The F# Formatting library lets you do things like re-order code and hide less important code for documentation purposes. You can create clean documents presenting code as a narrative. http://tpetricek.github.io/FSharp.Formatting/literate.html

I’ve been using Literate Haskell for a project recently. It’s a heavily mathematical data-crunching algorithm, in the region of a few thousand lines of executable code. This is the first time I’ve tried writing literate code in a major professional project, and it’s been interesting to see how the reality matched up with my initial expectations.

To me, the biggest practical difference is whether your documentation is primarily written as a tutorial or for reference on demand. Presenting ideas in a natural order for tutorial purposes is useful to someone coming to the code for the first time, or if you’re coming back to look at a module a while after you first wrote it when all those little details are no longer so familiar.

In my case, the documentation is generated using LaTeX and so can also include maths, diagrams, tables and other illustrative material right there next to the associated code, as well as providing a natural place to put module- or program-wide summary information to give an overview of how everything fits together. Like a mathematical paper, it takes a little effort to present all this extra documentation well. However, it’s hard to overstate how much better it is if you’re trying to understand some intricate mathematical code that you wrote three months ago and the actual maths is right there and is then directly reflected in the shape of the code.

Others have mentioned that literate code might be harder to maintain in the long run. I’m not sure how realistic that really is, based on my experience so far. If you’re making code changes significant enough that you’d want to reorder the whole presentation, you’re probably rewriting significant chunks of that documentation anyway, and it’s not as if our editing tools can’t cope with moving code and/or text around.

What does suffer, significantly in my experience, is the scannability of the code. Those few thousand lines of Haskell I mentioned produce well over 100 pages of typeset documentation at this point. That’s partly because of the extensive textual notes and mathematics and diagrams and so on. It’s also partly because typeset documentation is naturally more spaced out because of things like headings and blank lines. But the fact remains, if I looked at just the source code in my usual editor, I’d probably have 50–100 lines visible in a single window, and I can open several of those windows at once on a big screen. If I’m looking through the literate documentation (or the source file from which it is generated) then I am probably only seeing one third to one half of that at most, and crucially, that code only appears a few related lines at a time, often a single function or a small family of related type definitions. Since Haskell itself is rather uniform in appearance and tends to be written by composing very short elements anyway, this makes finding and understanding individual fragments of code noticeably harder than regular coding when you want to refer back to something in isolation.

So far, I’m finding that a price worth paying, at least for this kind of heavily mathematical work with me as the sole developer. In practice, I don’t actually want to refer to a small code fragment on its own very often. I’m more likely to come back to a whole module, skim the entire literate documentation for it (probably just a few pages) to remind myself of how it all fits together, and then not need to jump around understanding small individual elements in isolation. Still, there is definitely a cost here, and it definitely affects how I read and understand the code as I’m working with it later. I suspect some of that cost would be incurred anyway by using Haskell, or any other language and programming style that emphasize composing many small elements, but using literate programming does exaggerate the effect, and so far I’ve found that to be its biggest drawback over more conventional styles.

Is the Knuth book on literate programming any good?

Anyway I thought this article would have been better with a few examples. I'm still not any closer to understanding how the tangling process works.

Literate programming - the original IPython notebook

"I think I understand better now why literate programming hasn’t gained much of an audience. I used to think that it was because developers hate writing prose. That’s part of it."

Right, and that's why it's so difficult to find developer-written blogs and articles and tutorials online....