We make great layoff candidates because most of our code is something other people can take over maintaining. They keep the jackass who makes things nobody else understands.
In the jackass. Until now I thought I’m surrounded by people who cannot understand reasonably complex code. Currently I hope that both can be true at the same time. I’ll enjoy my job safety, although now more humbly.
I told the last one that his confessed difficulties with documenting his code probably come not from a failure of literary skill but a failure to write code that can be explained.
That sounds like a useful distinction, I like it - thanks for sharing. I hope they draw the right conclusions, i.e. start writing code that can be explained instead of documenting current code with "# Too complex, cannot be explained"[1].
I think the ultimate observation is that when you write a piece of code incrementally, you are memorizing your own code with small alterations that fit into working memory. And if you write the code for yourself instead of other people, you write it in exactly the shape that fits most compactly into your own brain instead of anyone else’s. When you write for others it gets a bit bigger (which is probably why people balk).
But the bigger issue is that nobody else has memorized your code. So they have to fit the entire codebase as it currently exists into working memory. And since that is impossible it can take them months or even years to get as proficient as you are. Because they have to memorize it piecemeal to understand it, and unlearn false assumptions they couldn’t disprove until later. And meanwhile you keep adding new changes to the code. That’s a you problem, not a stupid coworkers problem.
If you’re very friendly you can bring a handful of coworkers along so you have the bus numbers, but any new hire still has the cognitive load problem.
The way out of this is to eschew “power” (Principle of Least Power), condense the core of the problem to its essential complexity, and write discoverable code - code that leaves breadcrumbs that invite a curious user to peek into functions where the real work is done. Which for instance polymorphic recursion absolutely does not do.
