Literate programming: presenting code in human order
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:<p>A previous employer (a subdivision of a global top ten defence company) used literate programming.<p>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:<p><pre><code>    &lt;&lt;Initialise hardware&gt;&gt;
    &lt;&lt;Establish networking&gt;&gt;
</code></pre>
and so on, and each of those variously break out into smaller chunks<p><pre><code>    &lt;&lt;Fetch next data packet&gt;&gt;
    &lt;&lt;Decode data packet&gt;&gt;
    &lt;&lt;Store information from data packet&gt;&gt;
    &lt;&lt;Create new message based on new information&gt;&gt;
</code></pre>
The layout of the chunks often ended up matching functions in the source code and other such code constructs, but that wasn&#x27;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.<p>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.<p>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&#x27;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.<p>The chunks helped a lot. If you had a chunk you&#x27;d called &lt;&lt;Initialise hardware&gt;&gt;, that&#x27;s all you&#x27;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&#x27;t quite fit what was needed into something, the design needed revisiting.<p>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.<p>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&#x27;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).<p>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&#x27;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.<p>Why don&#x27;t I see it elsewhere? I suspect lots of people have simply never considered coding in a literate style - never knew it existed.<p>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&#x27;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.<p>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&#x27; 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&#x27;s code without offending anyone&#x27;s precious sensibilities (we&#x27;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&#x27;t typing, they&#x27;re seen as not working, so management would have to be properly on board. I don&#x27;t think literate programming is incompatible with the original agile manifesto, but I think it wouldn&#x27;t survive in what that seems to have turned into.