← Back to blog

The Psychology of Code: Why Your Brain Hates That Legacy Class

Feb 19, 2026

The Psychology of Code: Why Your Brain Hates That Legacy Class

Every developer has experienced it.

You open a file. You scroll. You sigh. You consider switching careers.

The code works. It even passed tests. But your brain reacts as if it just stepped on a Lego brick.

Why?

Because code is not just technical. It is psychological.

Inspired by Victor Rentea's talk on clean code and cognitive load, let's explore why some code feels elegant --- and some code feels like emotional damage.

1. Your Brain Has Limited RAM

Your brain is not Kubernetes.

It does not auto-scale.

It has limited working memory. When reading code, your brain can only juggle a handful of concepts at once. When a method spans 200 lines with nested conditionals and mysterious boolean flags, your mental RAM crashes.

Example of brain-friendly code:

public boolean isEligible(Customer customer) {
    return customer.isActive() && customer.hasValidSubscription();
}

Example of brain-hostile code:

public boolean process(Customer c, int x, boolean f1, boolean f2) {
    if (c != null && x > 0 && !f1 && (c.getSub() != null || f2)) {
        return true;
    }
    return false;
}

Both may work.

Only one respects your cortex.

Small methods reduce cognitive load. Clear naming reduces interpretation cost. Your brain appreciates both.

2. Naming Is Emotional Design

Names are not just labels. They shape understanding.

Consider:

• data
• tmp
• value2
• handlerNew

These names create anxiety.

Compare that to:

• invoiceRepository
• retryPolicy
• emailNotificationService

One forces you to reverse-engineer meaning. The other communicates intent immediately.

Ambiguous naming makes your brain ask:

"What is this thing? Should I trust it?"

Clear naming says:

"Relax. I've got you."

3. Complexity Feels Unsafe

When code is deeply nested or full of side effects, your brain switches into defensive mode.

It starts scanning for danger.

• Where could this break?
• What else does this method modify?
• Why is this global variable changing?

High complexity triggers stress because it increases uncertainty.

Flattening logic, reducing nesting, and isolating side effects makes code feel predictable --- and predictable systems reduce anxiety.

Predictability is comfort.

4. MVPs Still Need Psychological Hygiene

Now, before we go full "Clean Code monk mode" --- remember: not every project is a NASA satellite.

MVPs are allowed to be simple.

But simple does not mean chaotic.

Even in an MVP:

• Use clear names
• Keep functions reasonably small
• Avoid unnecessary abstraction
• Add minimal logging

You don't need five architectural layers. You do need basic readability.

Future-you will thank present-you.

And future-you holds grudges.

5. Code Is Read More Than It Is Written

Developers love writing code.

But most of the software lifecycle is reading code.

Maintenance is basically professional archaeology.

If someone (often you) needs 20 minutes to understand what a method does, that's expensive --- cognitively and financially.

Readable code:

• Reduces onboarding time
• Speeds up debugging
• Makes refactoring less terrifying
• Lowers emotional resistance to change

Unclear code makes developers procrastinate changes.

And procrastination leads to legacy.

6. The Hidden Cost of Cleverness

Clever code feels smart in the moment.

Until someone else reads it.

Overly compact expressions, magical generics, or "one-liner wizardry" may impress in a code review --- but they increase mental effort later.

Clarity beats cleverness.

Always.

Unless you're writing a code golf competition entry. Then go wild.

7. Psychological Safety in Systems

When systems are:

• Well-structured\
• Well-logged\
• Clearly named\
• Predictable

Developers feel safe making changes.

When systems are:

• Fragile\
• Implicit\
• Side-effect heavy\
• Poorly documented

Developers avoid touching them.

And avoidance is how legacy grows.

Clean code is not about aesthetics. It is about psychological safety.

Closing Thoughts

Code is not just for machines.

It is for humans with limited memory, limited attention, and limited patience.

When you write code, you are designing an experience --- for the next person who reads it.

That person might be:

• Your teammate
• A new hire
• Or you, on a Monday morning, six months from now

Respect their brain.

Keep it simple. Name things well. Reduce surprises.

And remember:

If reading your own code makes you slightly uncomfortable...

Your brain is trying to tell you something.