> I would prefer to read someone's mental model of how the code works than the code itself.
I find this is often true for me. If there's a bunch of code that I'm having a particularly hard time understanding, it's usually because I don't actually have a working mental model of what the thing is supposed to do.
Problem is, with complex systems often the way to record the mental model is something like a design document, and getting programmers (including myself) to write thoughtful natural language to accompany our code is a constant uphill battle against business pressures to ship more.
> Problem is, with complex systems often the way to record the mental model is something like a design document, and getting programmers (including myself) to write thoughtful natural language to accompany our code is a constant uphill battle against business pressures to ship more.
In my experience, the more common issue isn't that an initial design doesn't exist, but that it was never touched again after being approved before the implementation, so issues that came about when actually trying to implement it and the corresponding changes to the design aren't captured anywhere, let alone changes made during the ongoing maintenance after it's actually put to use. The only thing more frustrating than a lack of intent written down somewhere is an intent written down that doesn't actually match what's going on, and then having to try to track down if the intent _ever_ matched the actual design, and if so when (and if you're lucky, why) that changed.
I think the success of notebooks can provide a positive influence here.
They give text and readability a higher priority than traditional source code artifacts, and it really might only take a fresh IDE/plugin and comment meta-syntax to make that more normal in production code as well.
Agreed. It seems to me that doctests (i.e. code examples in docs that also count as tests, common in Python and Rust codebases) can possibly cover parts of this.
I find this is often true for me. If there's a bunch of code that I'm having a particularly hard time understanding, it's usually because I don't actually have a working mental model of what the thing is supposed to do.
Problem is, with complex systems often the way to record the mental model is something like a design document, and getting programmers (including myself) to write thoughtful natural language to accompany our code is a constant uphill battle against business pressures to ship more.