←back to thread

Cognitive load is what matters

(github.com)
1455 points nromiun | 2 comments | 30 Aug 25 12:58 UTC | HN request time: 0.002s | source
Show context
alphazard ◴[30 Aug 25 21:14 UTC] No.45078066[source]▶
The bit about "smart developer quirks" looks suspiciously like the author only understands code that they have written, or is in a specific style that they recognize. That's not the biggest driver behind cognitive load.

Reducing cognitive load comes from the code that you don't have to read. Boundaries between components with strong guarantees let you reason about a large amount of code without ever reading it. Making a change (which the article uses as a benchmark) is done in terms of these clear APIs instead of with all the degrees of freedom available in the codebase.

If you are using small crisp API boundaries to break up the system, "smart developer quirks" don't really matter very much. They are visible in the volume, but not in the surface area.

replies(5): >>45078114 #>>45078206 #>>45078208 #>>45078237 #>>45078727 #
1. zakirullin ◴[30 Aug 25 21:38 UTC] No.45078208[source]▶
Having a clear and minimalistic API doesn't mean that the underlying code is easy to understand. It's good when things just work and you can use an API, but most of the time you have to dig whatever is under the rug.
replies(1): >>45079415 #
2. alphazard ◴[31 Aug 25 01:02 UTC] No.45079415[source]▶
> Having a clear and minimalistic API doesn't mean that the underlying code is easy to understand.

Doesn't need to be. The API tells me what it does, hopefully there is a test suite to assure me. I can add to the test suite if I have a question, or want to lock in a behavior.

When it's a third party library, everyone assumes it's supposed to work? but when it's a system in the same repository, all of a sudden all bets are off, and you need to understand it fully to get anything done?

> It's good when things just work and you can use an API, but most of the time you have to dig whatever is under the rug.

If most changes require simultaneously changing multiple areas of the code, such that changing one system implies changing every other system with roughly equal probability, then it's not well designed.

I don't know what else to tell you. It's going to be hard to iterate or maintain that system, in part because it requires a high cognitive load. None of the code in such a system provides any cognitive leverage. You can't rule out, or infer behavior of a large amount of code, by reading a small amount.

If such a system is important, then part of the strategy has to be to improve the architecture.