Reading code is confusing. As a software engineer, I accept it as a natural part of the process; it's par for the course. Even though reading code is essential to my work, I rarely think about it. I kind of just ... do it. But there's more to reading code than meets the eye.
This post explores cognitive processes in relation to reading code.
Most of the time I'm familiar with the code I'm reading. I know the programming language well enough. I have enough context to solve the problem at hand. I look up stuff as I need it. This is business as usual.
A lot of the time I'm not as familiar with the code. I don't have a solid grasp of the programming language. I could use more clarity on what exactly I'm trying to solve. Even after looking up stuff, I need to piece everything together.
And every so often, I have absolutely no idea what I'm reading. Everything is alien to me. And it's mentally exhausting.
It's intuitive that not all states of confusion are equal.
States of Confusion
There are 3 broad states of confusion.
- Knowledge-based confusion.
- Context-based confusion.
- Capacity-based confusion.
The following sections explain each state with a code block. Please do your best to read the code and determine what it does before carrying on.
Knowledge-based Confusion
+[-->-[>>+>-----<<]<--<---]>-.>>>+.>>..+++[.>]<<<<.+++.------.<<-.>>>>+.Don't worry if your best guess is an absolute shot in the dark. That's expected.
Without core knowledge of the syntax or semantics of this code. And no familiarity with a similar programming language for that matter. It's an alien language.
A lack of foundational knowledge causes knowledge-based confusion.
Context-based Confusion
const date = new Date(Date.UTC(96, 1, 2, 3, 4, 5));
console.log(date.toUTCString())If you used some documentation - good job!
You identified that this code prints a timestamp. But you may have needed more details about the Date object interface e.g. .UTC(), .toUTCString(), etc.
This code is easy to follow once you have the relevant information in context.
A lack of relevant information that would otherwise end confusion, causes context-based confusion.
Capacity-based Confusion
var gcd = function(a, b) {
if (!b) {
return a;
}
return gcd(b, a % b);
}
console.log(gcd(20, 8));This was likely a lot to process in your head. Keeping track of the recursive calls, different arguments, etc. is taxing.
It's like counting up in powers of two. At some point, you run out of brain power.
A lack of enough brain power to process code in your head causes capacity-based confusion.
What's happening inside the brain?
The brain stores and interacts with memories using 3 different memory systems:
- Long-term memory (LTM)
- Short-term memory (STM)
- Working memory (WM)
This section explains each system and how it relates to states of confusion.
Long Term Memory
LTM involves deeply ingrained memories. It has a lot of room to store memories (an entire lifetime's worth). Memories like your phone number, favorite movie quotes, and programming fundamentals live here.
When the LTM can't retrieve fundamental memories, it causes knowledge-based confusion. Like in the first code block written in an esoteric programming language.
Short Term Memory
STM involves transient memories. It's relatively limited in size, and it's used for memories like what you ate for lunch yesterday. Or for keeping track of variable references in the context of a program.
In the second code block, your STM kept track of the date variable across the first two lines. And also kept track of the relevant information from the documentation.
If you forgot everything already, it's because the STM purged the information by now. That information is no longer relevant in context.
When the STM can't retrieve relevant memories, it causes context-based confusion.
Working Memory
WM involves processing memories rather than retrieving them. It's extremely limited in size, and can only work with a few pieces of information at once. Whether it's creativity, simple arithmetic, or stepping through code in your head. WM is responsible.
WM overloads when there's too much to handle, and causes capacity-based confusion. Like in the third code block, where there's not enough brain power to go around.
Closing Thoughts
You now have a much closer look at how the brain works when it comes to reading code!
Confusion State | Memory System | Memory Size |
Knowledge | Long-term | Large |
Context | Short-term | Small |
Capacity | Working | Tiny |
While I've simplified cognitive processes as discrete units, the reality is quite different. The brain is complex and the processes interact in ways well beyond the scope of this post.
All models are wrong, but some are useful.