I think the responses of "Well, it doesn't astonish me" and "principle least my surprise" point to something deep about how to write code for other humans: As

I think the responses of "Well, it doesn't astonish me" and "principle least my surprise" point to something deep about how to write code for other humans: As a field, we would benefit greatly from learning more cognitive science. A core suggestion of John Osterhout's book A Philosophy of Software Design is to have well-named modules with 'thin' interfaces which accomplish a reasonably-deep set of responsibilities. But...why? Working Memory -- Humans have limited Working Memory. If you give a function: - A clear name. - Few simple parameters. - No side-effects not in the name. - No GOTOs or exceptions. then a human can glance at it, put the name and parameters into working memory, and carry on. But if you split up a namable responsibility across multiple files, then a human reading the codebase to understand data flow would need many more open editor windows or to hold much more info in working memory.