Donald Knuth. “Literate Programming ()” in Literate Programming. CSLI, , pg. I believe that the time is ripe for significantly better documentation of . Literate programming: Knuth is doing it wrong. Literate programming advocates this: Order your code for others to read, not for the compiler. Literate Programming is also the name of DonKnuth’s book (ISBN One speculation for the reason behind Knuth’s pushing of LP is that according to Stanford’s.

Author: Viramar Zull
Country: Mexico
Language: English (Spanish)
Genre: Medical
Published (Last): 18 October 2005
Pages: 444
PDF File Size: 3.91 Mb
ePub File Size: 9.15 Mb
ISBN: 746-9-36637-967-4
Downloads: 84472
Price: Free* [*Free Regsitration Required]
Uploader: Kajibar

It makes it harder to make changes. The story you start telling is knnuth what you end up with later, after you’ve completed all the non-trivial features and major assumptions have fallen through. Going back and fixing the story as you go along is expensive. Writing the story after it’s litdrate is too late – the business value is in the product’s shipped functionality, not in the development artifacts.

We have programmiing alternate method of understanding how software developed, which is to look at revision control commits. This method falls more in line with the techniques of development and the mnuth evolution of the codebase. Recall that revision control methods were still being improved well after Knuth wrote about literate programming, and the available systems, where people used them and a lot of shops didn’tweren’t nearly as fine-grained back in the ‘s.

I tried using “Leo”, an outlining and literate programming text editor, for a project. Although the documentation capability was nice temporarily and gave me an additional method of structure and organization, the hooks messed around with some formatting and refactoring operations, and most of the time, the benefit wasn’t clear.

The time I spent on the documentation could have gone – from my current perspective – into making the code smaller and simpler. At the time, I didn’t know how that would be possible, thus I focused on defending against the complexity by adding more.

A lot of our preconceptions about what makes code both look good and behave well are temporary. That makes it hard to come up with a sensible system of organization, as we’ll put effort in to enumerate and categorize only to discover that it falls apart.

Literate programming

Your mention of commit messages resonates strongly with my own professional experiences, and I’m sure with many others’ as well. Several months ago I started working with a commercial code base that has about 3 years of commits and over a dozen contributors, but very few inline comments. Navigating and refactoring it is usually a fairly reasonable process due to well-named symbols, module organization, and test cases. When that’s not enough though, I pull up the “git blame” history in my editor, and a rich story unfolds, telling me things like about how old a block of code is, how recently that one line in the middle was changed, and why that seemingly benign extra bit of code is sitting there.

Sometimes the commit messages aren’t as detailed as one might prefer, but you can often still get a lot of useful insight just from the date stamps. WorldMaker on Aug 17, I’ve been accused of not writing enough comments in the code itself and then writing “novels” in the commit messages and “Literate Revision Control” is probably the best name for that sort of style. I’ve been liking how Visual Studio’s CodeLens now available in cheaper SKUs in brings focus to commit history specific to logical units in the code methods and classes.

Now I’m curious where you might be able to push things if you purpose built a “Literate Revision Control” tool and what sort of strong “epic poem” style of commit messages would best produce useful “novelizations” of a codebase Jetbrains IDEs also have an awesome interface to see the git history of some piece of code.


It depends on your programming style.

Literate Programming

If it’s a typical convoluted, constantly refactored OO code – then, yes, literate programming won’t help. If your code consists of a lot of DSLs, clearly separated from each other, each implemented in a small, compact, readable programmng – then you won’t have to change that much in the existing code.

In my experience this style is a very good match for a literate programming. I’m fairly happy with Leo for “documenting” my Puppet nodes – I create programminy Leo node for each Puppet node or node regex with a link to the node definition, and a link to the “documentation” node of each class included for that node.

Classes have “documentation” nodes which similarly link to their definition, files and templates and to documentation nodes of any classes included by the class. There’s no more prose involved than you’d expect in-line. I find the structure extremely useful to re-discovering how a particular node is configured.

If there are simplifications available, I find the structure makes them visible. Perhaps the above would be less useful for ,iterate traditional code. Could you describe in more detail how you used it? I have a long programjing of improvements I’d like to see made to Leo e.

Building such tools being out of scope for my day job, my re-imagined version won’t be available any time soon. Prorgamming used Leo for a solo game project – AS3 code – made over the course of about a year. I also took some notes with it during the same time. It was over five years ago now. I don’t remember all the details of what I did, but: First of all, there were some encoding conflicts that were introduced when mixing Ligerate with other editors.

When I go loterate to the project now, it doesn’t compile because of the encoding errors. It’s fixable, I’m sure. Second, I had more classes than I needed. The secret to writing compact game code is – basically – to write few real classes and rely on plain old data and a large main loop.

As it was, they were literatte up and down some hierarchy, splitting pieces of the main loop into different classes, running a custom scripting language to drive Litertae, etc. I had all sorts of ill-considered ideas at the time and no real guidance. By the end I wasn’t really using Leo, because it wasn’t solving my problems. Looking back on it now, I have a style that can more naturally accommodate a literary programming approach because I’m more likely to write a straight-line solution first.

But I would not rely on an external tool again as I don’t want the dependency. I love the comment of “defending against complexity by adding more. I also love the juxtaposition of this comment and the other top comment. If your source code files, version control commits, code review comments on those commits, and bug discussion threads are all cross-referenced in a unified Web interface, many problems just go away.

IMO it solves the same litedate that literate programming was supposed to solve, but less intrusively and more reliably. Also I agree that code organization is often a bit overrated. I really like linear “hack hack hack” code, even if it has a bit of copy paste, and dislike highly abstract OO progrsmming. On the flip side, I happen to be fanatical about good naming, which is easier if the code is programimng concrete than abstract.

Thanks, this was useful. It does survive, in a certain sense, in scientific programming and data science. Both iPython notebooks and Rmarkdown are a sort of literate programming, although with the emphasis on the text more than the code.


In that setting, the executable artifact is not really more important than the explanation of why the code does what it does, so the extra overhead is justifiable. The “notebook” paradigm in Mathematica is another good example; arguably it’s as much a part of the experience as the underlying Wolfram kernel.

I just wanted to note that this isn’t some newfangled invention, Mathcad did interactive notebooks kunth The Pander R package renders objects into Pandoc’s markdown. I’ve programminh using literate programming for 15 years on many projects. The largest and most visible one is Axiom https: I’ve talked to Knuth. He claims he could not have programminh MMIX without literate programming. Literate programming is knutu valuable but you only understand that once you really try it.

I gave a talk on this subject at the WriteTheDocs conference: The book “Implementing Elliptic Curve Cryptography” is another example. Suppose your business depends on a program.

Literate programming – Wikipedia

Suppose your team leaves they all do eventually. Suppose you need to change it THAT’s why you need literate programming. Nobody is going be around to remember that the strange block of code is there to handle Palm Pilots. Companies should hire language majors, make them Editor-in-Chief, and put them on every programming team.

Nobody checks in code until there is at least a paragraph that explains WHY this code was written. Imagine a physics textbook that was “just the equations” without any surrounding text.

That’s the way we write code today. It is true that the equations are the essence but without the surrounding text they are quite opaque. Imagine how easy it would be to hire someone. You give them the current version of the book, send them to Hawaii for two weeks, and when they return they can maintain and modify the system as well as the rest of the team. Do yourself a favor, buy a copy of Physically Based Rendering. Consider it to be the standard of excellence that you expect from a professional programmer.

Then decide to be a professional and hold yourself to that standard. Techniques for Creating Reusable Software by Hanson which was also written in the literate programming style. Just correcting the Wikipedia link: Aside from that, i tend to agree with you, and i aspire to the same. Unfortunately laziness and time constraints often get the better of me, though.

Unless someone puts a comment above it? Literate programming isn’t the only method of documenting code. You’re essentially doing LP if you have enough high quality comments. It doesn’t really matter what tool you use for this. No, you really aren’t. To the point that if you aren’t going out of your way to represent the narrative flow of what you are writing, you are probably not going to see any benefit.

Yes, you are ;- The thing is, as I wrote in the other comment, that “modern” like Lisp, as someone noted ;- languages already allow you to structure the code as you see fit. You don’t have to define or even declare functions before their first use in the file, you can easily extract any part of the code into a function or method and you can place it anywhere you want. There are many mechanisms available for threading the context through functions, which makes direct, textual inclusion simply not needed.