TL;DR overview
- Cognitive complexity is a code quality metric that measures how difficult code is to understand, going beyond cyclomatic complexity to account for control flow structures that are genuinely hard for humans to follow.
- High cognitive complexity increases the risk of bugs, slows onboarding of new developers, and makes future changes more expensive—making it a practical indicator of maintainability debt.
- The post shares five actionable quality code techniques for reducing cognitive complexity, such as extracting helper functions, simplifying nested conditionals, and replacing complex logic with more expressive patterns.
- SonarQube measures and tracks cognitive complexity across codebases, highlighting the most problematic areas so developers can prioritize refactoring efforts for maximum maintainability impact.
Introduction
Chances are, you are very familiar with the feeling of trying to understand someone else's (or even your own) old code. It definitely made sense six months ago, but between then and now it has become more 'magic eye' than map. If you focus on how hard your code is to understand today, tomorrow will be a lot easier. Cognitive Complexity is Sonar's measure to help you do exactly that! This blog dives into how Cognitive Complexity is calculated and how it can help you write great code!
Tip #1: Write code your team will love you for
When collaborating with a team, it’s very important to consider how well the code you write will be read later in development. Cyclomatic Complexity was first introduced as a way to gauge how easy it is to test and maintain a module's control flow. While it's pretty good at assessing testability, the mathematical model behind it falls short when it comes to measuring maintainability. In this video, we observe a few examples:
Tip #2: Life isn’t all full speed ahead
Linear code is your friend. If all code was just a sequence of commands listed one after another without any looping or mucking about, then it would be pretty easy to hold that in your head. As soon as you add loops, or decisions that branch the code, it becomes more and more difficult to understand. For this reason, the Cognitive Complexity score for your code will increase by 1 each time you do that. In this video, we see how one’s score adds up when branching and looping are introduced. Sonar can help you see where the complexity is in your code, and seek our opportunities for refactoring.
Tip #3: Nesting things can make things bad really fast
Nested code is harder to understand and doing more inside nested code compounds how much effort it takes to hold everything in your head. In this video, we see how doing looping or branching inside other loops and branches can drastically impact your Cognitive Complexity score.
Tip #4: Useful things don’t increase complexity
There are a number of constructs that are designed to make code clearer. Cognitive Complexity scoring is smart enough to understand these constructs do good, so using them won't increase your Complexity score. In this video, we observe a handful of examples that can help educate users on how Sonar’s Cognitive Complexity algorithm works.
Tip #5: Find the way with Sonar
In this video, we see how Sonar helps users understand complicated code through Cognitive Complexity scoring. Whether you look at the issue in your IDE with SonarQube for IDE or in SonarQube Cloud or SonarQube Server, you can see each of the points in the function that impacts your overall score.
In conclusion
Cognitive Complexity provides a fresh take on complexity modeling. It yields method complexity scores that align well with how developers perceive maintainability. This has been a brief overview of how Sonar measuring Cognitive Complexity can help you write code that is easy to understand. Your team and future you will thank you for it!
Want to know more?
Check out this White Paper on Cognitive Complexity by Community Manager, Ann Campbell!
