Cognitive Load is a guide that frames code quality through the lens of cognitive load, the mental effort required for developers to understand and work with code.
The project addresses a fundamental problem: developers spend far more time reading and understanding code than writing it, yet most best practices are based on subjective aesthetics rather than human constraints. The guide identifies cognitive load as a measurable, real constraint rooted in how human working memory functions. It distinguishes between intrinsic cognitive load, which stems from the inherent difficulty of tasks and cannot be reduced, and extraneous cognitive load, which arises from how information is presented and can be significantly minimized. The project focuses on reducing extraneous cognitive load by examining concrete practical examples of how code presentation choices create unnecessary mental burden.
The guide is particularly relevant for developers working on unfamiliar codebases or processing large amounts of generated code, such as output from language models. It suits teams that prioritize maintainability and readability over architectural complexity or trendy technologies. The project emphasizes that clever implementations and sophisticated patterns, while intellectually satisfying to their authors, often impose high cognitive costs on future readers and maintainers. It argues that reducing cognitive load should be a primary concern in software development, especially in an era where developers frequently encounter code they did not write.
The project maintains documentation in multiple languages and includes specialized guidance for AI agents. It is presented as a living document that evolves over time, indicating ongoing refinement of its core concepts and examples based on practical experience and community feedback.
