I really appreciate the detailed comment! I love talking about this stuff. --- You're absolutely right that code reading is a non-linear activity and that won

I really appreciate the detailed comment! I love talking about this stuff. --- You're absolutely right that code reading is a non-linear activity and that won't ever change.[1] I'm not trying to make all code reading a linear activity; that would be truly quixotic. I want to keep the code organized for the convenience of the writer but still provide an initial orientation for newcomers, when they aren't concerned with error handling or precise interface boundaries. --- Finding the right version to look at is part of the solution, as you noticed. But there's a second half: making sure the information newcomers need is actually in the repo. Somewhere, anywhere. My sense is that existing codebases don't actually contain all the information needed to truly comprehend them. The context the system runs in, and all the precise issues it guards against. Tests are a huge help here, but I'm constantly making changes to code that I tested in some other terminal or browser window with some complex workflow. Then I often save the code in one window and close the other window. That's a huge loss of information, and it's compounding over and over again in current platforms. All because there are manual tests we can do that aren't easily encoded as automated tests. It's certainly possible to port my ideas to an existing stack so that more tests can be represented. But how do we recover all the knowledge that has been lost so far? --- I don't think the problem is that authors make mistakes[2]. They understand the domain far better than an outsider like me. No, the problem is that authors don't capture everything that is in their heads, and that means that I make mistakes when I try to build on their work. One selfish reason I care about making the global structure of my codebase comprehensible is the very slight hope that others can take it in new directions and add expertise I won't ever gain by myself, in a way that I and others can learn from. --- "...most of the causes you identified (backwards compatibility considerations, churn in personnel, vestigial features) can be real and unavoidable: there may be features that are needed only for (say) users of old systems but still cannot simply be removed. The best that can be hoped for is to make this fact clearer, not to make them go away." If the codebase is more comprehensible and captures all compatibility and other concerns as tests, then it becomes easy to fork. Users of old systems could stay on one fork and others could be on a simpler fork that deletes the compatibility tests and the code that implements them. That way they aren't paying a complexity penalty for what they don't use. The tests would make it tractable to exchange code between the two forks, even if they diverge pretty far over time. Or so I hope. --- Thank you again for your detailed feedback. Now I have a sense of a few more issues to avoid in my writing. [1] That's partly my complaint with typography in LP: we end up polishing one happy path to death. [2] If you notice places in my writing that strengthen this impression that I'm trying to reduce mistakes, I'd really appreciate hearing about them. I'm explicitly trying to avoid the failure mode that I think projects like TUNES fall into, of trying to come up with the one perfect architecture.