Code that makes sense to you is much easier to write than code that makes sense to others.

· Bits and Bobs 12/2/24

Production code is defined by needing to be understood by other people.

Prototype code, or hobby project code only has to make sense to you.

And also specifically future you, many years in the future, who may have forgotten the details.

Prototype code merely needs to achieve the required outcome to a moderate degree of fidelity.

But production code needs not only to achieve the required outcome, to a high degree of robustness and fidelity, but also needs to be able to be understood by more than one person to help maintain and fix it.

The ease of understanding of a bit of code is of paramount importance.

'Clever' code, or highly opinionated in a non-typical way is a liability all else equal in those contexts.

Production code may need to be debugged by someone else under duress: dealing with a bug in production with a fire raging.

To make code that makes sense to someone else requires you to model what their priors are, what the baseline type of person who might be in this codebase might think like and be able to understand.

Idiomatic code is "boring" in a load-bearing way; the reader doesn't have to load lots of other context into their head, they can shorthand understanding.

The same way a chess master can remember legal board positions orders of magnitude better than a chess novice, but has no particular advantage remembering a board where the pieces are distributed randomly.