Thomas J. McCabe introduced Cyclomatic Complexity in 1976 as a way to guide programmers in writing methods that "are both testable and maintainable". At SonarSource, we believe Cyclomatic Complexity works very well for measuring testability, but not for maintainability. That's why we're introducing Cognitive Complexity, which you'll begin seeing in upcoming versions of our language analyzers. We've designed it to give you a good relative measure of how difficult the control flow of a method is to understand.
To get started let's look at a couple of methods:
These two methods share the same Cyclomatic Complexity, but clearly not the same maintainability. Of course, this comparison might not be entirely fair; even McCabe acknowledged in his original paper that the treatment of
case statements in a
switchdidn't seem quite right:
On the other hand, that's exactly the problem with Cyclomatic Complexity. The scores certainly tell you how many test cases are needed to cover a given method, but they aren't always fair from a maintainability standpoint. Further, because even the simplest method gets a Cyclomatic Complexity score of 1, a large domain class can have the same Cyclomatic Complexity as a small class full of intense logic. And at the application level, studies have shown that Cyclomatic Complexity correlates to lines of code, so it really doesn't tell you anything new.
That's why we've formulated Cognitive Complexity, which attempts to put a number on how difficult the control flow of a method is to understand, and therefore to maintain.
I'll get to some details in a minute, but first I'd like to talk a little more about the motivations. Obviously, the primary goal is to calculate a score that's an intuitively "fair" representation of maintainability. In doing so, however, we were very aware that if wemeasure it, you will try to improve it. And because of that, we want Cognitive Complexity to incent good, clean coding practices by incrementing for code constructs that take extra effort to understand, and by ignoring structures that make code easier to read.
We boiled that guiding principle down into three simple rules:
- Increment when there is a break in the linear (top-to-bottom, left-to-right) flow of the code
- Increment when structures that break the flow are nested
- Ignore "shorthand" structures that readably condense multiple lines of code into one
With those rules in mind, let's take another look at those first two methods:
As I mentioned, one of the biggest beefs with Cyclomatic Complexity has been its treatment of
switch statements. Cognitive Complexity, on the other hand, only increments once for the entire
cases and all. Why? In short, because
switches are easy, and Cognitive Complexity is about estimating how hard or easy control flow is to understand.
On the other hand, Cognitive Complexity increments in a familiar way for the other control flow structures:
do while, ternary operators,
else if/elsif/elif/..., and
else, as well as for
catch statements. Additionally, it increments for jumps to labels (
continue) and for each level of control flow nesting:
As you can see, Cognitive Complexity takes into account the things that make this method harder to understand than
getWords - the nesting and the
continue to a label. So that while the two methods have equal Cyclomatic Complexity scores, their Cognitive Complexity scores clearly reflect the dramatic difference between them in understandability.
In looking at these examples, you may have noticed that Cognitive Complexity doesn't increment for the method itself. That means that simple domain classes have a Cognitive Complexity of zero:
So now class-level metrics become meaningful. You can look at a list of classes and their Cognitive Complexity scores and know that when you see a high number, it really means there's a lot of logic in the class, not just a lot of methods.
At this point, you know most of what you need to get started with Cognitive Complexity. There are some differences in how boolean operators are counted, but I'll let you read the white paper for those details. Hopefully, you're eager to start using Cognitive Complexity, and wondering when tools to measure it will become available.
Eventually, we'll probably add class/file-level Cognitive Complexity rules and metrics. But we're starting with Baby Steps.