This rule raises an issue when the code cognitive complexity of a function is above a certain threshold.

Why is this an issue?

Cognitive Complexity is a measure of how hard it is to understand the control flow of a unit of code. Code with high cognitive complexity is hard to read, understand, test, and modify.

As a rule of thumb, high cognitive complexity is a sign that the code should be refactored into smaller, easier-to-manage pieces.

Which syntax in code does impact cognitive complexity score?

Here are the core concepts:

• Cognitive complexity is incremented each time the code breaks the normal linear reading flow.
  This concerns, for example, loop structures, conditionals, catches, switches, jumps to labels, and conditions mixing multiple operators.
• Each nesting level increases complexity.
  During code reading, the deeper you go through nested layers, the harder it becomes to keep the context in mind.
• Method calls are free
  A well-picked method name is a summary of multiple lines of code. A reader can first explore a high-level view of what the code is performing then go deeper and deeper by looking at called functions content.
  Note: This does not apply to recursive calls, those will increment cognitive score.

The method of computation is fully detailed in the pdf linked in the resources.

What is the potential impact?

Developers spend more time reading and understanding code than writing it. High cognitive complexity slows down changes and increases the cost of maintenance.

Function Abs(ByVal n As Integer) As Integer ' Noncompliant: cognitive complexity = 5
    If n >= 0 Then    ' +1
        Return n
    Else              ' +2, due to nesting
        If n = Integer.MinValue Then      ' +1
            Throw New ArgumentException("The absolute value of int.MinValue is outside of int boundaries")
        Else                              ' +1
            Return -n
        End If
    End If
End Function

They should be refactored to have lower complexity:

Function Abs(ByVal n As Integer) As Integer  ' Compliant: cognitive complexity = 3
    If n = Integer.MinValue Then    ' +1
        Throw New ArgumentException("The absolute value of int.MinValue is outside of int boundaries")
    Else If n >= 0 Then             ' +1
        Return n
    Else                            ' +1
        Return -n
    End If
End Function

Resources

Documentation

• Sonar - Cognitive Complexity

Articles & blog posts

• Sonar Blog - 5 Clean Code Tips for Reducing Cognitive Complexity