Cognitive Load in Code Design

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);
    }
}

References

• ↗ https://en.wikipedia.org/wiki/Cognitive_load

Tags

Related Terms