# A Growing Developer Manifesto Says Cognitive Load, Not Style Dogma, Should Guide Software Design
By IO Digest Desk
A GitHub project titled `cognitive-load` was drawing attention for a blunt proposition: most software design advice should be judged by whether it reduces the amount of thought required to work safely in a codebase.[16134]
The document describes itself as a living text, updated through June 2026, and argues that many best practices fail because they are driven by aesthetics, slogans, or subjective taste rather than by the practical experience of reading and maintaining code.[16134] Its alternative organizing principle is cognitive load: the amount a developer must keep in working memory to complete a task.[16134]
The source uses a simple human constraint to anchor that idea. It says the average person can hold roughly four chunks of information in working memory, and that once code comprehension pushes beyond that threshold, understanding becomes much harder.[16134] The implication is that software quality is not just about correctness or elegance. It is also about how much transient mental state a developer must reconstruct before making a change.
The document distinguishes between intrinsic and extraneous load. Intrinsic load comes from the problem itself and cannot be designed away. Extraneous load is added by the way the code is organized or presented and can often be reduced substantially.[16134] The repository focuses almost entirely on the second category, treating it as one of the most concrete forms of maintainability debt.
Its examples are intentionally practical. One recommendation is to introduce intermediate variables with meaningful names so developers can focus on the happy path instead of juggling preconditions in their heads.[16134] Another is to prefer composition over inheritance, because deep inheritance chains force readers to assemble behavior by traversing multiple classes before they can reason about one change.[16134]
The strongest argument, though, is against an overproduction of shallow modules. The document contrasts “deep” modules, which expose simple interfaces while hiding complex implementation, with “shallow” modules, whose interfaces are disproportionately complex relative to what they actually do.[16134] Too many shallow components, the author argues, make projects harder to grasp because developers must track not only each module’s role but also the interactions among all of them.[16134]
To illustrate the point, the source compares two personal projects of similar size. One had 80 shallow classes and became difficult to re-enter after a long pause because understanding it required rebuilding a large amount of contextual knowledge. The other had only seven deep classes and was much easier to pick back up.[16134] The argument is not for giant “god objects,” the repository says, but for components that hide complexity instead of exporting it as ceremony.[16134]
That framing also leads to a critique of popular interpretations of the single-responsibility principle. According to the document, developers often mistake “one responsibility” for “one tiny thing,” producing abstractions whose names and interfaces are more mentally taxing than their implementations.[16134] The author instead ties responsibility to the needs of a stakeholder or user rather than to arbitrary size limits.[16134]
The popularity of the repository suggests that many developers recognize the problem it describes. In an era of growing framework complexity and large volumes of AI-generated code, the cost of reading may matter even more than the cost of writing.[16134] If teams spend most of their time understanding existing systems, then any design rule that increases comprehension burden should face a higher bar.
The supplied evidence supports a clear summary of the project’s thesis: good software design is whatever reduces unnecessary mental overhead for the next person doing the work.[16134] That is less flashy than many architecture doctrines, but it may be precisely why the argument is finding an audience.
