68

I'd like to come back to the topic of educational codebases and explore whether the idea relates to literate programming (and if so how in particular).

Literate programming is an idea of Donald Knuth, who not only wrote a book about the concept, but also published two quite notable literate programs: TeX and Metafont. Alas, the Don Knuths of the world are few and far between, and the paradigm never found wide adoption. My understanding of it is that a literate program is an explanatory text first, and treats the code as itself is not the first class entity, but as an artifact that is derived from the text and prepared for compilation/interpretation in a seperate step. The order of reading and understanding for humans is more important that the order in which the program would be executed.

If the quality of the literate program is high, it likely also has educational value, but to the extent that a literate program is also a practical program (e.g. the examples of TeX and Metafont), although these certainly are worthy objects of study, I am not sure if they hit the the educational mark in a broader sense. At least they will not constitute the core of a hypothetical canon of educational codebases.

So, potential creators of educational codebases could find some inspiration for good writing about code out of the literate programming area (as opposed to only writing good code), but I think an educational codebase needs to treat code as first-class artifact, but this implies by no means that high-quality documentation is a second-class citizen. Just, that creating them is less intertwined as it were I one were to write primarily a literate program.