A Conversation About Cognitive Complexity

Jack: “Look, I don’t see what the big deal is with this cognitive complexity thing. If the code works, it works. Isn’t that what matters? As long as the feature does what it’s supposed to, why should I care how complex the code is?”

Hugo: “I get it. It’s tempting to think that way, especially when you’re on a deadline. But just because something works doesn’t mean it’s good code. You might not notice it now, but high cognitive complexity can lead to problems later.”

Jack: “I don’t see the issue. If the code runs, then it’s fine, right?”

Hugo: “That’s the thing — it’s not just about whether it runs today. Imagine someone else — or even you — coming back to that code six months from now. If it’s hard to follow, it becomes a maintenance nightmare. Cognitive complexity measures how hard it is for someone to understand the code, not just execute it.”

What is Cognitive Complexity?

Cognitive complexity assesses the mental effort required to understand code. Unlike cyclomatic complexity, which counts decision points like if and for statements, cognitive complexity looks at how code flows and how much mental juggling it requires. Things like deeply nested loops, unnecessary conditions, and jumping between files all add to it.

Jack: “But once the feature is done, it’s done. I’m not planning to change it again anytime soon.”

Hugo: “You’d be surprised. Bugs happen, features evolve, and customer requirements change. Now imagine trying to debug a piece of code with five levels of nested if statements. It becomes a headache. When code is too complex, even small changes can introduce new bugs or take longer to implement. And if only you understand it, you risk becoming a bottleneck for the team."

Jack: “Alright, but complexity is just part of the job, isn’t it? Writing software isn’t simple.”

Hugo: “Sure, but there’s a difference between necessary complexity and unnecessary complexity. You can write complex software in a way that’s easy to understand. For instance, deeply nested logic often adds unnecessary complexity. Returning early in functions instead of having a huge else block can make things easier to follow."

Reducing Cognitive Complexity

One simple way to reduce cognitive complexity is to use early returns instead of multiple else clauses. Take this example:

function processOrder(order) {
  if (order.isValid()) {
    if (order.hasItems()) {
      if (!order.isPaid()) {
        order.requestPayment();
      }
    }
  }
}

This code can be simplified by using early returns to reduce the nesting:ja

function processOrder(order) {
  if (!order.isValid()) return;
  if (!order.hasItems()) return;
  if (order.isPaid()) return;

  order.requestPayment();
}

The logic is the same, but the second version is much easier to follow.

Jack: “But I understand my own code. Why does it matter if it’s complex?”

Hugo: “Because you won’t always be the one maintaining it. Code is read far more often than it’s written. If another developer — or even you, months from now — has to figure out what your code does, high cognitive complexity means they’ll spend more time understanding it. This slows down future work, introduces the potential for errors, and increases frustration for the whole team.”

Jack: “Fair enough. But if I’m the one writing the code, why should others need to look at it?”

Hugo: “In a real-world project, no one owns the code forever. Other team members will eventually have to work on it — whether it’s for bug fixes, optimizations, or adding new features. High cognitive complexity can be like technical debt. It doesn’t hurt right away, but it builds up over time. When the code is hard to read, it takes longer for new developers to get up to speed, and making changes becomes riskier.”

Jack: “Okay, so how can I deal with it? Rewrite everything?”

Hugo: “No need for massive rewrites, but there are strategies to reduce cognitive complexity as you go. For example, break large functions into smaller, single-purpose functions. Instead of having 300 lines of code in one file, split it into reusable components or modules. You can also aim to reduce context switching — jumping between too many files or classes to understand one piece of logic increases cognitive load. Try to keep related logic together.”

Small Changes with Big Impact

One common cause of cognitive complexity is writing long functions or large classes that try to do too many things. Here’s an example:

function manageInventory(order) {
  if (order.isPaid()) {
    updateStock(order);
  } else {
    cancelOrder(order);
  }

  if (order.isDelayed()) {
    notifyCustomer(order);
  }

  // Other order-related tasks...
}

Breaking this function into smaller, more focused functions improves readability:

function manageInventory(order) {
  handlePayment(order);
  handleShipping(order);
}
function handlePayment(order) {
  if (order.isPaid()) updateStock(order);
  else cancelOrder(order);
}
function handleShipping(order) {
  if (order.isDelayed()) notifyCustomer(order);
}

This makes the code modular and easier to follow without changing its behavior.

Jack: “Alright, I see your point. But I worry that focusing too much on this might slow me down, especially with deadlines looming.”

Hugo: “That’s a valid concern. But in reality, taking time to write cleaner, simpler code usually speeds things up in the long run. Clean, well-structured code means faster debugging, easier onboarding for new team members, and fewer bugs during updates. You don’t have to tackle everything at once — start small. Even just reducing some nesting or breaking up long functions can make a big difference over time.”

Jack: “Alright, maybe I’ll give it a try on my next feature. My future self will probably thank me.”

Hugo: “Trust me, it will. Simpler code benefits everyone — including you.”