Want to Improve Code Quality? Focus on Cognitive Complexity.
The overlooked metric that is crucial to crafting quality code.
We’ve all, to some extent, measured the time it takes to run code and the space our code occupies in memory, but how often have we measured how easily understood our code is by the human mind? Probably not as much.
However, higher-level programming languages were created because they’d be understandable to humans. Logically, the understandability of our code is then crucial. But how do we go about measuring such a thing?
G. Ann Campbell of SonarSource has proposed a way of measuring a code’s understandability through a measure she calls cognitive complexity.
Measuring Cognitive Complexity
Code can become hard to intuitively understand for several reasons. The main reasons highlighted by Cambell are as follows:
- There are breaks in the “linear flow of code”
- “Flow breaking structures” are nested
We’ll look into what each of these points means in just a bit.
Before we do, we should note that according to Campbell’s definitions, code is not to be considered more (or less) complex for using shorthand commands that a language provides.
For example, consider the following Python code for determining which number of a given 2 is greatest.
This code above is considered to be just as complex cognitively as the code written below.
Now that this is clear, let’s return to the two factors that make code more cognitively complex according to Cambell’s proposed measurement system.
Breaks in Linear Flow of Code
The linear flow of code refers to when code flows seamlessly from top to bottom. Breaks in code can be caused by a variety of structures that make readers have to jump back and forth between lines, thus making code harder to understand. Below is a list of features that cause breaks in code:
- Loops
- Conditionals
- Catches
- Switches
- Sequences of logical operators
- Recursion
- Jumps to labels
Nested Flow-Break Structures
Nested statements demand more mental capacity from a reader and so it should come as no surprise that they increment cognitive complexity. Conditionals, loops, and catch structures can all count as nested flow-break structures and thus increment cognitive complexity.
Extensions/Plugins that Calculate Cognitive Complexity For You
Thankfully, you don’t have to slave away calculating the cognitive complexity of your code. Some plugins and extensions will do this for you, such as the one in the image below.
Conclusion
To write better code, it’s important we try to minimize cognitive complexity. We can do this by making sure our code flows linearly and by limiting our use of nested structures.
That’s all! Thank you for reading :)
To read further about cognitive complexity and gain a deeper understanding, consider visiting the following link to a document written by Cambell.
To read up about time complexity, consider visiting the following article :
