17

Sometime ago Hillel Wayne wrote about educational codebases, which he defined as being designed to be read and studied. Although very few codebases qualify under this definition, and in the light of counter-arguments against the notion, that one should learn to write code by reading good examples, as argued by Peter Seibel in Code is not literature, I am still intrigued by the idea. So: to what educational end would I want to read a codebase?

Hillels own example demonstrates idiomatic usage of a specific programming language. This is low-hanging fruit, which can reasonably be achieved with a rather small amount of code. It is certainly of importance to novices to a language, but idioms aren't widely transferable skills, which in my books makes them the least interesting goal for bespoke educational code.

A more worthwhile goal, especially for learners with little industry experience, could be code comprehension strategies as a meta-skill. Once employed, one is likely thrown in at the deep end and expected not to drown. A codebase that were indeed designed for such an exercise would require different properties, than one for the sake of demonstrating idioms. For example, I think at least some noise that you would want to keep out of demonstrations of best practices, would actually be necessities. You'd actually need to have irrelevant files, superfluous things, distractions, sub-optimal, even defective parts, to make clear that not all files are of equal importance, to make it tangible to its students that aspects can and even need to be filtered out with confidenence, to demonstrate how you find suitable entry points, to make them develop an intuition for when to follow the control flow depth-first and when to stay on the same abstraction level and go broad, all while not allowing yourself to get overwhelmed.

Another purpose, which for more seasoned practitioners would also be of interest, would be to enhance your sense for software design. In the trenches of the work life it can sometimes be a challenge to prevent N years of experience to not actually be a single year of experience repeated N times. So, as part of a continuing self-education, educational code could provide exposure to exemplary good problems, add new mental models, and help to map abstract ideas to their concrete applications. As one of my favorite Alan Kay quotes goes: "perspective is worth 80 IQ points".

I leave it at describing purposes and goals. Where to find or how to design such codebases would be a topic for another time.