Cognitive Load in Code Design
debt(d7/e5/b7/t5)
Closest to 'only careful code review or runtime testing' (d7). While phpstan and phpmd can flag some symptoms like cyclomatic complexity or long parameter lists, cognitive load itself is not directly measurable by automated tools. Deep nesting or mixed abstraction levels require human judgment to assess whether they actually impair understanding. Most cognitive load issues surface during code review or when developers struggle to modify the code.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix suggests limiting function length, reducing parameters, and improving naming — these are not one-line changes. Reducing cognitive load typically requires restructuring functions, extracting methods, and reorganizing code within a component. It's not architectural rework, but it's more than a simple parameterised fix.
Closest to 'strong gravitational pull' (b7). Cognitive load patterns apply across all contexts (web, cli, queue-worker per applies_to) and represent a persistent structural choice. Once a codebase establishes patterns of high cognitive load — deep nesting, mixed abstractions, unclear naming — every future change is shaped by navigating that complexity. New developers must adapt to the existing style, and refactoring requires touching many interconnected pieces.
Closest to 'notable trap (a documented gotcha most devs eventually learn)' (t5). The misconception states that developers often confuse problem complexity with code complexity, believing hard-to-understand code reflects a hard problem rather than poor structure. This is a documented gotcha — many developers learn over time that complexity can be extrinsic (from code design) not just intrinsic (from the domain), but it's not immediately obvious to those new to the concept.
Also Known As
TL;DR
Explanation
Cognitive load theory (Sweller, 1988) distinguishes intrinsic load (inherent complexity of the problem), extraneous load (complexity caused by poor presentation — naming, structure, abstractions), and germane load (mental effort building understanding). In code: deep nesting, poor naming, surprise side effects, and mixed abstraction levels all increase extraneous load without adding value. The goal is to reduce extraneous load so developers can focus cognitive resources on the actual problem.
Common Misconception
Why It Matters
Common Mistakes
- Deep nesting forcing readers to track multiple conditions simultaneously.
- Mixing abstraction levels in one function — high-level business logic alongside low-level string parsing.
- Surprising side effects — functions that do more than their name implies.
- Too many parameters — each parameter is a variable the reader must hold in working memory.
Code Examples
// High cognitive load — nesting, mixed levels, surprise:
function process($d) {
if ($d) {
if (is_array($d['u'])) {
foreach ($d['u'] as $u) {
if ($u['a'] === 1) {
$r = file_get_contents('https://api.example.com/u/' . $u['id']);
$j = json_decode($r);
mail($u['e'], 'Hi', $j->msg); // Side effect buried in loop
}
}
}
}
}// Low cognitive load — flat, named, no surprises:
function notifyActiveUsers(array $users): void {
$activeUsers = array_filter($users, fn($u) => $u->isActive());
foreach ($activeUsers as $user) {
$message = $this->messageApi->getWelcomeMessage($user->id);
$this->mailer->send($user->email, 'Hi', $message);
}
}