cognitive-load: a prose playbook built on one four-chunk ceiling

The whole argument rests on four chunks in working memory

The definition is one sentence: cognitive load is how much a developer needs to think in order to complete a task. What fills that budget is named concretely as values of variables, control flow logic, and call sequences, because those are what a reader has to hold while parsing a function. The ceiling is the average person holding roughly four such chunks, and the document links that figure to an issue in its own repository rather than to a study. Past the threshold, understanding gets much harder. From there the argument reframes the usual question: since we spend far more time reading and understanding code than writing it, the load we impose on readers is the thing worth engineering against. The motivation has sharpened recently, the introduction says, because in the AI age a developer has to process a lot of LLM generated code with their own brains. That is a claim about attention, not about syntax, and every example in the document is scored by how many facts the reader is holding at that line.

Intrinsic load is declared unfixable, so only extraneous load is fair game

The document splits the concept in two and then writes off half of it. Intrinsic load is caused by the inherent difficulty of a task, cannot be reduced, and sits at the very heart of software development. Extraneous load is created by the way the information is presented, comes from factors not directly relevant to the task such as a smart author's quirks, and can be greatly reduced. Extraneous is the only type the rest of the text tries to lower, and every Go example belongs to it. What this division cannot do is tell you which one you are looking at. The test for whether a function is intrinsically hard or extraneously hard is the reader's judgment, and the introduction opens by dismissing exactly that kind of judgment, blaming most buzzwords and best practices on being imagined rather than real and on aesthetics and subjective judgment. The framework therefore inherits the weakness it set out to remove. In practice a reader can label the same six-line function intrinsic in one review and extraneous in the next, both within the rules, and the disagreement never surfaces because nothing in the document produces evidence for either claim.

The scale is three marks and a four-fact line, and the author calls it simplistic

Load is rated with three marks used consistently throughout the text. A plain brain mark means fresh working memory and zero load. The same brain doubled means two facts are now being held and load has increased. A third, overwhelmed-looking mark is reserved for cognitive overload, defined as more than four facts. The author adds that the brain is much more complex and unexplored and that this is the simplistic model they will go with, which is an honest disclaimer and a real limit. These marks are self-reported estimates written into the reader's head, not measurements, so they cannot be computed, diffed, or attached to a pull request. Worse for tooling, they are relative to the reader's current familiarity: the same function drops from overload to zero load once you have seen it twice, which is exactly the situation the document says is most expensive, the first encounter by someone who did not write the code. The marks also live inside the Go comments in the examples, so the snippets carry their own annotations and the annotation is part of what you read.

Complex conditionals get three named booleans instead of one boolean chain

The first worked example is a condition that has grown past what a reader can hold. The chain tests a value against a constant, then requires either of two conditions, then requires a pair that must both hold, with comments recording that the previous condition has to be true, that one of the two alternatives must be true, and that by the third clause the reader is already overwhelmed. The rewrite introduces intermediate variables with meaningful names, and the same conditions become this:

isValid = val > someConstant
isAllowed = condition2 || condition3
isSecure = condition4 && !condition5
if isValid && isAllowed && isSecure {
    ...
}

The point is that the reader no longer has to remember the conditions, because descriptive variables carry them. The limit is that this is not a mechanical transformation, and the document gives no test for choosing good names. isValid, isAllowed, and isSecure could have been a, b, and c. Rename the chain and it is still the same chain with the same number of facts to hold, so the work is in the naming and the naming is unguided. The examples also use ellipsis bodies, which means nothing here compiles and nothing here can be pasted into a repository as a starting point. Consequence for a reader: this refactor costs a review, and if the new names merely restate the operators you have changed four lines and learned nothing.

Early returns delete the preconditions you were holding

The nested-if example walks down three levels, each one narrowing the input the reader is thinking about: valid input, then valid and secure input, then the work itself, with the load mark climbing at every level. The flat version guards with returns instead, checking that the value is valid, returning if it is not, checking that it is secure, returning if it is not, and then doing the work with the comment that if execution reached this point everything is fine. The mechanism is stated plainly: attention goes to the happy path only, which frees working memory of all the preconditions that nesting forced you to carry. The limit is scope. Early returns flatten cleanly when the guards are independent checks on the same value, which is the case in the example, and badly when each level depends on the previous one, since flattening changes the order in which conditions are tested. A function that acquires a resource, opens a scope, or has several branches also does not flatten by swapping keywords; the return has to be moved somewhere that still has cleanup to perform. Consequence: in code with teardown or dependent guards this is a behavioural refactor to be reviewed, not a formatting change to be applied on the way past.

The inheritance chain adds a subclass you were not told about

The inheritance example starts from a task that would be simple if the tree were shallow: change a few things for admin users. Then the class hierarchy arrives, AdminController extends UserController extends GuestController extends BaseController, and the reader is walked up and down it. Some of the functionality lives in BaseController. Basic role mechanics were introduced in GuestController. Things were partially altered in UserController. The reader finally arrives at AdminController and starts coding, and only then learns that SuperuserController extends AdminController, so a change to the class they were told to edit can break something in a class further up the chain that they have not opened. The load marks climb through the walk and reach overload at the moment of surprise. The advice given is to prefer composition over inheritance, and the document declines to elaborate, pointing to a video instead. What it does not give is any threshold. Five controllers is presented as a problem; four is never discussed, and there is no rule for where a hierarchy stops being expensive. Consequence: the diagnosis arrives without a limit, so turning it into a design decision becomes a matter of taste, which is the failure mode the introduction complained about in the first place.

Deep modules invert the small-methods rule, on evidence from two projects

The document takes on the mantras that methods should be shorter than fifteen lines and that classes should be small, and calls them somewhat wrong. Its replacement vocabulary is depth. A deep module has a simple interface over complex functionality. A shallow module has an interface that is relatively complex compared with the small amount of work it does. Too many shallow modules hurt in a specific way: you must hold each module's responsibilities in mind and all their interactions at once, and to understand one shallow module you first have to read the functionality of every module related to it. Jumping between shallow components is mentally exhausting, and linear thinking is more natural to humans. Information hiding is paramount, and shallow modules do not hide much complexity. The evidence is two personal projects, each about 5K lines of code, one with 80 shallow classes and the other with 7 deep classes, both unmaintained for a year and a half. Returning to the first meant untangling interactions between those 80 classes and rebuilding an enormous amount of cognitive load before coding could start; the second was grasped quickly. The closing line is a quote from John Ousterhout, that the best components provide powerful functionality yet have a simple interface. The limit is that two projects by one author at one size measure recall, not design.

Ten translations, no code, and the newest tag is from 2024

What you can install here is nothing. The repository root holds a LICENSE, eleven README files, and an img/ directory, with no source directory, no build script, and no manifest, so the whole deliverable is prose under CC-BY-4.0. The English README is the one that carries the June 2026 update date and calls itself a living document, and the project links a blog post, a separate file written for AI agents, and translations into Chinese, Japanese, Spanish, French, Korean, Turkish, Brazilian Portuguese, Vietnamese, and Nepali. Each language lives in its own file, and nothing in the repository explains how the copies are kept in step, so the date printed inside one language says nothing about the others. The commit history is healthier than the tags: the last push to main is dated 2026-10-26, while the newest release, v1.3.0, is dated 2024-11-09, after v1.2.0 on 2024-09-01 and v1.1.0 on 2024-01-07. Consequence for anyone wiring this into a review process: pinning a release gets you text well over a year older than the main branch, and the rules you cite will be from a document that has since been rewritten.

Editorial conclusion

Use this document when a reviewer, or you after eighteen months away, is complaining that a function is hard to follow. Do not use it as a linter, as a class-count target, or as evidence about working memory, since the four-chunk figure is linked to an issue in the repository rather than to a study, and the author says the term is used informally. Before quoting the deep versus shallow module rule in a design review, check the two projects behind it: same author, roughly 5K lines each, unmaintained for a year and a half. And read the current text rather than the v1.3.0 tag, because the newest release predates the prose by well over a year.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-4.0
3. README
4. Releases
5. zakirullin/cognitive-load on GitHub