Code readability depends on how well written code fits human working memory. Working memory handles only about four so-called chunks at once, bundles of information pulled from long-term memory. Good naming, short method signatures and avoiding side effects cut down the number of active chunks and make code readable for everyone on the team.
Key Takeaways
- Working memory can handle only about four chunks at once, which is why a method call with an object, a method and two arguments already hits that limit.
- Chunks in long-term memory aren’t uniformly small units: a single chunk can activate lots of detail at once, and that’s what makes abstraction so powerful.
- Good naming means the chosen term activates the same chunk in as many readers as possible, so it triggers associations similar to the author’s.
- State transitions in code overload the brain, because it can notice a change of state but struggles to replay it internally, which gives side-effect-free functional programming a cognitive edge.
- Pair programming synchronizes how two developers form chunks: whatever the navigator doesn’t understand is a reliable sign that others will find the code hard to read, too.
Code Readability Is a Matter of the Brain, Not Taste
Whether code is readable comes down to how well a human brain can process it. That’s the starting point for Stefan Mandel and Peter Guntermann, who put code readability on a cognitive footing. Both work as software developers and have spent a lot of time on clean code. Instead of simply accepting the rules from Robert C. Martin’s book, they went looking for the reasoning behind them: why do these recommendations work in the first place?
The problem that got them started is familiar to anyone who works in a team. A junior writes a method with four arguments, a senior colleague says you don’t do that, and when asked why, the best answer is a pointer to a book. That only goes so far. Nobody can know a thousand books by heart, and some of them even contradict each other.
The better answer sits one level deeper. Once you understand how the brain takes in code, you can work out good practices yourself and explain them to others. Instead of “you just don’t do that,” you can say: your brain is overloaded, so cut down the information.
How Working Memory Processes Code
When you read code, your brain handles only a limited amount of information at once. Stefan and Peter distinguish between working memory and long-term memory. Working memory is the part that actively computes as you step through a line of code, and that’s the part with tight limits.
The central unit here is the chunk. A chunk is a bundle of information stored in long-term memory. Every word in the code, every variable, method or class name, maps to a chunk like this. Anyone who has learned a programming language carries chunks for its grammar and can run the code in their head.
Working memory can handle only about four chunks at once. Psychology talks about four plus or minus one. From the fifth element on, things get really hard. Four is the limit, and anything below it is easy going.
That’s why a typical line of code stays manageable. An assignment involves an object, a method and an argument. That’s three chunks, and the result only appears at the end, so it takes up no space before then. Working memory handles three chunks with ease.
Experience Makes Chunks More Powerful
More experience doesn’t make working memory bigger. It makes the individual chunks more powerful. The four-chunk limit applies to everyone. What differs is how much sits behind a single chunk.
Chunks come in different sizes. In computer science, the closest concept is abstraction. Anyone who knows design patterns and hears the word “Observer” immediately has a picture of the underlying concept without walking through every detail.
The brain works differently from a computer here. It doesn’t just compute symbolically on the abstraction. The detail chunks underneath an abstraction fire at the same time. Four pieces of information at once, but each can carry lots of detail, so you can process far more in a single step.
Code Is Communication
Code is a form of communication, and the receiver needs the same chunks as the sender. You have a requirement, turn it into a feature and write code. Someone else reads it later, and that someone is often you, just a few weeks on.
A term like “Observer” only helps if the other person knows it. Use a chunk the reader doesn’t have, and you’re talking into thin air. Readable code happens when the chunks on both sides are wired up in a similar way and associated with the same things.
That has a practical consequence for teamwork. You don’t write for your own, possibly odd idea. You write for your teammates. So computer science involves a lot of communication work long before a single line compiles.
Why Descriptive Names Often Miss the Mark
Good naming means that as many people as possible understand the same thing by a term. Naming is known as one of the hardest problems in computer science, and for good reason. A name has to hit the right chunk in the reader’s head.
Descriptive names are often misunderstood, though. Some people think they’re no longer allowed to use short identifiers. That’s not true. An x for the x-coordinate is a convention, and nobody has to write xCoordinate. You can give the reader some credit.
The opposite mistake does just as much damage. If you can’t capture a concept in one word, you sometimes end up putting a whole sentence into the variable name. Every part of that name is processed as a chunk. If the name is too long, you’ve forgotten the beginning by the time you reach the end. Short and precise beats long and descriptive.
Long comments don’t fix this. An endless comment in front of a variable wears the brain out, because you have to read it carefully before you get to the code. A good comment is better than nothing. But if you can build the meaning into the name, that’s the better choice.
How Many Arguments a Method Can Take
The common advice of about two arguments per method follows directly from the four-chunk limit. When you read a method call, you don’t just process the arguments. You also keep in mind which method is being called and on which object.
So with two arguments, four chunks are already in play: the object, the method and the two arguments. A third argument makes five, and that’s where you lose readers who can’t cope with five.
There’s a way out. An abstraction that sensibly bundles two parameters brings the chunk count back down. The price is generality. If you deliberately want to keep a method flexible, you can’t invent a new abstraction for every call, and you have to leave the arguments side by side as equal chunks.
State and Side Effects Overload the Brain
Side effects are hard to follow because the brain is bad at replaying state transitions internally. If a method quietly increments a counter in the background, you have to hold that state in your head on top of the actual flow.
That’s exactly why functional programmers advise against side effects. A chunk can’t be rewritten at any speed you like. When you reassign a variable, suddenly a different value sits behind it, and the old association no longer fits.
“The brain is very well equipped to perceive changes of state, but not to reproduce them internally.”
(Stefan Mandel)
The same logic explains why high cyclomatic complexity is so tiring. You have to carry every condition that led you to a particular spot in the code. At some point, working memory is full of branches, you start pushing information out, and your results get sloppy.
Metrics Filter Out Noise but Don’t Replace Judgment
Software quality metrics are a useful but incomplete indicator of readability. They’re neither sufficient nor necessary, and now and then a metric can simply be gamed.
The common metrics are broadly in line with the chunk model. High cyclomatic complexity points, with some probability, to unreadable code. But there’s complex code that’s still easy to read, and there’s unreadable code whose problem lies somewhere else entirely.
Naming, for one, escapes every metric. No technique can judge whether readers will assume the right thing behind a name. Metrics do the legwork and filter out what’s obviously unimportant. When it comes to naming, though, any check can be sidestepped.
Readable Code as a Team: Synchronizing Chunks
Shared chunks come from shared experience, and the most important way to build them is simply to talk to each other. The brain creates chunks when you experience events. People who share the same events develop similar ideas.
Several practices aim at exactly that:
- Automate code formatting. A formatter makes sure the presentation doesn’t add to the reader’s load.
- Keep variables short-lived. A variable that lives longer than it needs to has to be buffered in your head the whole time. That overloads you and everyone else.
- Avoid abbreviations. Three-letter abbreviations are a classic. If they don’t help understanding, drop them.
- Use pair programming. If the driver has an odd idea of what makes a good chunk, the navigator notices right away. Both form the same chunk at the same moment, and this synchronized reinforcement creates shared understanding.
One pattern gives the weak spot away. If you can’t read your own code after two weeks, you created a chunk once while writing and never used it again. Stefan calls this ad hoc chunking: plausible in the moment, but never reinforced because it had no lasting value. If something is hard for the navigator to grasp, it’ll be hard for others too. That’s when it pays to sharpen the code.
What AI Assistants Add to Code Readability
AI assistants like Copilot help with understanding, but they tend to overproduce. Anything that can talk can also ramble, and an assistant will quickly bury you in suggestions. On the other hand, you can ask when something is unclear and get an explanation.
A self-experiment shows where the limits are today. Asked to make an example more readable, the tool reliably lengthened the names, stretched method names to several words and always added four lines of documentation on top.
The real joke was in the details. A method called “difference of squares” was supposed to compute x² - y², but it calculated (x - y) * (x + y) instead. Mathematically equivalent, but as a justification for the name, unreadable. The direct form would have been less efficient, but easier to understand.
AI tools produce explanations like these mechanically, not thoughtfully. For one other job, though, they’re useful right away: explaining a regular expression, exactly where humans tend to give up.


