> If you document your mental model of how the code works, I can probably map the code to your mental model and understand the code.

I agree.

This is something that I tried to do with my best project. [1] Only time will tell if I succeeded because it's really hard to document a mental model; it's like trying to explain to yourself what water is when you're a fish. [2]

[1]: https://git.gavinhoward.com/gavin/bc/src/branch/master/manua...

[2]: https://www.theguardian.com/books/2008/sep/20/fiction

This is great! I don't know if I'll have a project that I expect to last long enough to worry about bus factor, most of the work I do is either throw away stuff for myself or already part of a large shared team effort. But I love the idea. It's long but I skimmed it quickly and I think it's got a very good level of detail and is overall very readable with just the right amount of snark. :)

Thank you so much!

I wrote it in snatches of time nearly always late at night, so the snark just...happened. I was worried how it would be taken, so thank you for the encouragement, including about the level of detail.

I love it, I think I’m going to take some of these ideas for a literate programming thing I’m working on. Also props for proving that jagoff wrong.

Level of detail is something I think a lot about lately. Interviews go off the rails with candidates who answer in too much detail or not enough. Meetings go off the rails with non-actionable proclamations or tedious line-by-line details.

Machine generated / doxygen / javadoc documentation is the worst. I'd rather read the code, but code can also be difficult to read even if it's functional, especially when it's optimal. So having a guide to the code written by someone who knows how it is all laid out is pretty much the best case scenario.

That's some really handy documentation, thank you for sharing!

I like how you document each file.

Yep I absolutely agree. As the old quote goes:

"Show me your flowchart and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won't usually need your flowchart; it'll be obvious." -- Fred Brooks, The Mythical Man Month (1975)

Its always mystifying to me how often programmers try to show me a new concept in their code starting with some complex functions. Start with your data structures. What data are you storing, why, and when? If you show me that, the code that actually moves that data around is usually pretty obvious. (And if not, your code will be 10x easier to understand once I understand the context).

Little sidenote:

people usually try to explain the appeal of typescript by "static type checking leads to fewer errors, etc."

conversely i think the real reason is that it can show you the shape of the data at every step by simply hovering your mouse over a function/variable.

typescript is great because it enforces documentation

> 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.

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.

> 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 do this for all code I add devs to or hand off to. For instance, startup code I walk away from and hand over to contractors. A markdown doc with some high-level concepts + a hierarchical bulleted list explaining the module structure goes a long way.

it's amazing how uncommon this is in the big business world. Individuals have pride, cogs do not. I've been in both camps. Currently I'm a cog because it's better for my life at the moment. I'm frustrated by the lack of simple documentation - but at the end of the day I'm not really interested in fixing it.

I’m sure there is a real name for this, but I tend to call it a “Document of Intent”. It isn’t meticulously trying to explain every nuance, it’s a coarse treatment of the purpose of things and what they’re meant to do.

I started doing that with my own project after I reverted a (correct) change a few weeks later because I forgot to write down the original reasoning anywhere. No other contributors so far, so I can't say how much it helps on that front, but it has helped me a lot and I feel safer making big changes without fearing I'll break anything.

The entry point docs are here: https://github.com/trane-project/trane/blob/master/src/lib.r...

The bigger problem is when the code works (ish) but it’s clear that the lone developer didn’t even have a mental model of how the system works.

It’s usually very easy to see in a codebase when someone was flailing, and they wouldn’t be able to explain how or why this line of code works any better than you could. They just have strong conviction that this line of code needs to be there, because it was there at the stage in their flailing that things started working.

And to be clear, this can probably happen just as easily with a codebase with multiple developers.

Agreed, that sort of documentation is pure gold when done well.

It's something I always try to pay forward by doing in my own code. For example, one of my own lone-developer projects was an STB-style single-header <canvas>-like rasterizer library for C++. I started the implementation half of the library with a short overview of the rendering pipeline's dataflow and the top-level functions responsible for each stage:

https://github.com/a-e-k/canvas_ity/blob/f32fbb37e2fe7c0fcae...

> This might be unusual but I would prefer to read someone's mental model of how the code works than the code itself.

I prefer doing easier things rather than harder things also.

That's why I hate Spring and similar technologies. They autostart things everywhere. Even from library jars. So terrible.

If I would write Java program for myself, I wouldn't use Spring. I would use dependency injection, but I would construct all objects manually, calling their constructors and setters. I did that, it works, it maintainable. Some repetitive code, but it's so much easier to reason about compared to reflection monsters or autogeneration nightmares.

> This might be unusual but I would prefer to read someone's mental model of how the code works than the code itself.

The hypothesis under Peter Naur's (the N on BNF) "Programming as Theory Building" paper is that transmitting (by talking) the mental model is far more important than other format of documentation to understand a system.