Reading code

Designing Dev Tools with Cognitive Load in Mind

What a developer has to hold in their head to make one change, and how tools can help.

Matt Kindy · · 6 min read

As software systems grow more complex, developers have more to keep in their heads. A single development task might require understanding service boundaries, database schemas, API contracts, infrastructure dependencies and security implications, all while keeping enough focus to write good code. The tools we use to manage this complexity often add to that burden.

Part of the reason is that development tools shape how we think about our systems and how we work with them. When a tool doesn’t match the way developers naturally think, or makes them switch context constantly, it adds mental overhead that hurts both productivity and code quality. I think developer tools should be designed with that load in mind, and to do that it helps to be precise about what kinds of load there are.

Understanding Cognitive Load in Software Development

Cognitive load theory, which John Sweller and his colleagues developed in educational psychology, provides a useful framework for understanding the mental demands of software development. The theory identifies three types of cognitive load: intrinsic (the inherent complexity of the task), extraneous (additional complexity from how the task is presented), and germane (the mental effort required to create lasting understanding).

In software development, each type shows up in its own way. Intrinsic load comes from the complexity of the problem itself. Extraneous load is often a byproduct of tools that force developers to contort their thinking, or of documentation that’s a chore to navigate. A common example is having to switch constantly between the IDE, a separate diagram tool and a wiki, each with its own interface and its own way of navigating. Another is having to grapple with infrastructure concerns while trying to implement a business feature.

Germane load includes the effort developers invest in understanding how the codebase turns into business value, such as how specific modules contribute to key features, or how architectural decisions affect whether the system can scale as the business grows. Tools that link technical components to business outcomes support this kind of load. Tools that keep the two in separate silos add to the extraneous load instead.

The three types of cognitive load in software development. Intrinsic: the complexity of the problem itself. Extraneous: added by how the task is presented, such as switching between the IDE, a diagram tool and a wiki, or grappling with infrastructure while building a business feature. Germane: the effort of understanding how the code turns into business value, which tools support by linking components to business outcomes. Intrinsic The complexity of the problem itself Extraneous Added by how the task is presented: switching between the IDE, a diagram tool and a wiki, or grappling with infrastructure to ship a feature Germane The effort of understanding how the code turns into business value
The three kinds of cognitive load, with the examples above.

Context Switching in Development Today

Today’s development environments make this load hard to manage, because developers switch context so often. They move between services, frameworks and levels of abstraction. In a short span of time, a developer might trace a request across several microservices, dive deep into a framework’s internals and then zoom out to consider what the change means for infrastructure. A single feature might require understanding:

  • Service boundaries and interactions
  • Database schema changes
  • API contracts
  • Infrastructure dependencies
  • Security implications
  • Performance considerations

Each of these demands mental resources, and switching between them adds overhead of its own. When the total load exceeds a developer’s capacity, development slows down, errors go up and frustration grows.

The Connection to Flow States

The cost of all this switching is clearest in what it does to flow. Software development, when it goes well, often brings on a state of flow, the deeply focused state where developers are fully immersed in their work and at their most productive.

Reaching flow takes a delicate balance. The task has to be challenging enough to hold a developer’s attention, but not so overwhelming that it exceeds what they can keep in mind. Today’s development environments make that balance hard to keep, because so much in them can break flow: a context switch, a pause to rebuild a mental model, or a tool that demands attention for itself.

In a 2014 study by André Meyer and colleagues, professional developers said their days felt productive when they finished many or big tasks without significant interruptions or context switches. I think focus improves the quality of the work as well, because deep focus lets developers hold complex relationships between parts of the system in working memory and reason about them well. The cognitive overhead of today’s development practices often interrupts that focus.

Because flow breaks so easily, the tools that reduce unnecessary cognitive load matter a great deal. They make development more comfortable, and they protect the deep focus and understanding that lead to better software. As our systems grow more sophisticated, the tools and practices we use have to account for our cognitive limits as well as our capacity for deep, focused work.

Design Principles for Reducing Cognitive Load

Well-designed tools and practices can remove a lot of this unnecessary load, and four principles guide how they do it.

Progressive disclosure means revealing information gradually, to match what the developer is focused on. Instead of showing every relationship in the system at once, a tool should present the context relevant to the current task and make it clear how to reach related information when it’s needed. For example, a tool can start with a focused view of the code the developer is working on and offer controls for exploring related components, where a less careful design would open with a massive diagram of the entire architecture.

Tools should match the natural mental models developers already use for their systems. Some developers think in terms of features or user stories, which can span many files and services. Others think in data flows, or in how particular services interact. File-based navigation remains popular because it maps well to how developers mentally organize code, so new tools should keep familiar patterns like that one and add to them.

Consistent patterns help for a related reason. When developers recognize a familiar structure, they can apply a mental model they already have instead of building a new one from scratch. Tools can support this by pointing out similar interaction styles, data structures or architectural approaches, which cuts the effort it takes to understand a part of the system that’s new to them.

Tools also need to preserve context across views and activities. When a developer goes from examining code to understanding the architecture around it, they shouldn’t lose their place in the mental model they’re building, or their train of thought. If a developer is exploring the definition of a particular object, for example, the tool should make it easy to get back to where they were in the code once they’ve finished.

Practical Applications

Development environments are beginning to put these principles into practice. IDEs increasingly build system-level understanding directly into the coding interface, which reduces the overhead of switching between tools and mental models. Inline documentation, dependency navigation and even architectural diagrams inside the IDE help keep developers in their flow.

Interactive visual maps of a system can help developers build and maintain a mental model of its architecture, as long as they support natural patterns of exploration and don’t overwhelm people with complexity. A well-designed visualization lets developers zoom, filter and focus on specific parts of the system, so their understanding builds up gradually.

Documentation helps most when it appears in context, right when it’s needed, because then nobody has to go searching for it. That might mean inline API documentation, architectural decision records (ADRs) linked to the code they concern, or system diagrams that are generated automatically and update as the codebase changes.

Looking Forward

As systems continue to grow in complexity, managing cognitive load becomes more and more important for both developer productivity and system reliability. The development tools that matter most will be the ones that extend what developers can hold in their heads without adding to the load.

To get there, tools will have to balance a comprehensive understanding of the system with the development patterns people already know, while supporting natural exploration and discovery and preserving context from one activity to the next.

Some cognitive load will always remain, because some complexity is inherent in software development. The aim is to remove the unnecessary mental overhead and to help developers build and maintain good mental models of their systems.

Conclusion

The future of software development depends on building tools that fit the way our minds work. Principles like progressive disclosure, natural mental models and context preservation can reduce cognitive load, and tools built on them can also raise developer productivity and deepen how well teams understand their systems.

Get the next essay

Follow the RSS feed to see each new essay when it goes up.