legibility in software

(related: growing up means becoming wrong, ask for evidence , Seeing Like A State)

Related to some interactions with NameRedacted recently, I want to connect the idea of legibility from Seeing Like A State to the idea of being a senior engineer, researcher, manager, or executive. NameRedacted asked that a particular function work with log-probs, rather than probs, even though there were compelling technical reasons for it to use probs. I think his motivation is, essentially, legibility: he wants TFP code to be uniformly structured and easy to navigate for someone with no knowledge of the particulars. This is crucial for software engineering writ large. Unlike the real world, where external legibility is often in opposition to the knowledge of locals, there are often no 'locals' in software. You generally don't live in the same code for a long period of time (there are of course exceptions), so even the original author will be a stranger to it when they return a few weeks or months later. Common patterns, structures, uniformity are necessary to help a large codebase remain navigable.

However, legibility is still often in opposition to what is locally optimal. It's especially in opposition to the knowledge of locals when those locals are building the village in the first place (ie, when you're first writing the code). There you see a novel way to fit intricate structures together, which might not be legible, but is better than the one-size-fits-all solution. Meanwhile you undervalue legibility, because you're still a local and haven't yet gone through the experience of visiting this village as a tourist.

Legibility shouldn't always win. Sometimes local practices are important. Sometimes local practices can 'bubble up' to improve the wisdom of the state-imposed rules while maintaining a new kind of legibility. But new engineers will be prone to making things too illegible because they haven't yet had the experience of being 'the state'---in this analogy, a senior engineer, who has to see the larger picture.

Similar issues arise in research. Work that's easy to understand, methods that are general, and fit into established conceptual frameworks, tend to be more valuable--thanks to legibility--than work that cuts some local slice of the intellectual world 'at the joints' but ends up being complex because in that zoomed-in view, the joints themselves are pretty complex. There's maybe a more direct connection in math. Theorems and theories need to be proved modularly, in terms of existing concepts. The abc conjecture proof is not legible, even if it makes good use of local knowledge, and so no one understands it or even knows if it's correct.