There’s a Japanese word I keep coming back to when thinking about what makes code good: Anshin (安心). Can I speak Japanese? No I can not. I am merely a thinly-veiled weeb. But the concept resonates deeply.

Breaking it apart gets you An 安 meaning peace, safety, ease - and Shin 心 meaning heart, mind, spirit. Together roughly translating to peace of mind. That feeling of calm certainty that everything is going to be okay.

It’s the feeling you get from a well-designed codebase. No hidden surprises. No bravado or ceremony, just the clarity you need to extract information efficiently or make an incision if needed.

Now, consider the last codebase you dropped into cold. Did it give you Anshin? Or did it hand you an investigation?

Information vs Investigation

This is the distinction I find most useful when evaluating code clarity: are you presenting the reader with information, or with a puzzle to solve?

Information says: here’s what this does, here’s what it needs, here’s what it returns, go over there to find out how this other thing works. The reader can make an informed decision and move on with their day.

An investigation says: good luck. The answers are in here somewhere. You’ll need to trace five files, hold three abstractions in your head, and develop a theory about what the original author might have intended, all before you even know where to start looking. Go grab a coffee.

We’ve all inherited investigations. We’ve all written them too - usually by accident, usually with good intentions. Clever abstractions that made perfect sense at the time. DRY principles applied so aggressively the code became write-only. We’re talking about the difference between “give me 5 minutes” vs “roll it back to last week and give me a day”.

The problem is, hiding complexity doesn’t remove it. It just relocates the burden - from the writer to every future reader. Instead of hiding complexity, or worse, dressing everything up to be uniformly complex, I’d argue there is more clarity in being upfront about it; leave it out in the open where it can be seen, understood to be complex, and managed.

If you abstract things behind layers of concept, whether for organisational purposes or secondary mechanics such as a particularly invasive testing strategy, your readers are losing an incredibly useful signal that says “this is the bit, pay attention” because everything looks the same. Code is complex by necessity sometimes, that’s okay - but you’re doing your readers a disservice if you make them work to uncover it.

Irreducible Simplicity

Anshin isn’t about making code “clean” or “beautiful” - those words are too subjective, too aesthetic. It’s about something more functional: reducing uncertainty. I’ve honestly stopped caring a whole lot about code aesthetics. It’s been over 20 years at this point and I’ve never once printed out some code and stuck it to my fridge or perched it above the mantelpiece. But I digress…

Clarity earns trust. More trust means less time spent second-guessing, verifying, defensive programming against surprises that might be lurking beneath the abstraction.

The goal is irreducible simplicity. Not the least code, but the least cognitive load. The point where removing anything else would actually make things harder to understand, not easier.

I wrote a few years back that reading code is understanding code. Any technique you use which imposes an investigation on the reader, even scrolling to the top of a file, increases the time to understand.

This isn’t about trying to coin a term or a movement, it’s just something I refer back to when making design decisions to think Will this give the reader peace of mind, or do I need to settle the fuck down?

3 Jan 2026 — P.G.