Cognitive complexity

Title short form	Cognitive complexity
Categories	Maintainability
Definition	Sum of partial complexities resulting, for example, from branches in the control flow of the POU and from sophisticated Boolean expressions
Further information	Cognitive complexity is a measure of the readability and comprehensibility of source code introduced by Sonarsource™ in 2016. It penalizes a strong nesting of the control flow and sophisticated Boolean expressions. The cognitive complexity is only calculated for structured text implementations.
Standard upper limit for the associated rule SA0178: Cognitive complexity	20

	Tip You can also use Command 'Show cognitive complexity for current editor' to display the increments for Structured Text directly in the editor.

The following samples show how cognitive complexity is calculated.

Sample: Control flow

Statements that manipulate the control flow increase the cognitive complexity by 1.

IF TRUE THEN              //+1 cognitive complexity
    ;
END_IF
 
WHILE TRUE DO             //+1 cognitive complexity
    ;
END_WHILE
 
FOR i := 0 TO 10 BY 1 DO  //+1 cognitive complexity
    ;
END_FOR
 
REPEAT                    //+1 cognitive complexity
    ;
UNTIL TRUE
END_REPEAT

The code snippet has a cognitive complexity of 4.

Sample: Nesting of the control flow

When nesting the control flow, an increment of 1 is added for each level of nesting.

IF TRUE THEN                      //+1 cognitive complexity
    WHILE TRUE DO                 //+2 (+1 for the loop itself, +1 for the nesting inside the IF)
        FOR i := 0 TO 10 BY 1 DO  //+3 (+1 for the FOR loop itself, +2 for the nesting inside the WHILE and the IF)
            ;
        END_FOR
    END_WHILE

    REPEAT                        //+2 (+1 for the loop itself, +1 for the nesting inside the IF)
        ;
    UNTIL TRUE
    END_REPEAT
END_IF

The code snippet has a cognitive complexity of 8.

Sample: Boolean expression

Since Boolean expressions play a major role in understanding source code, they are also taken into account when calculating cognitive complexity.

Understanding Boolean expressions that are connected with the same Boolean operator is not as difficult as understanding a Boolean expression that contains alternating Boolean operators. Therefore, each chain of equal Boolean operators in an expression increases the cognitive complexity.


b := b1;                             //+0: a simple expression, containing no operators, has no increment

The simple expression without operator has an increment of 0.

b := b1 AND b2;                      //+1: one chain of AND operators

The expression with an AND operation has an increment of 1.


b := b1 AND b2 AND b3;               //+1: one more AND, but the number of chains of operators does not change

The expression has an AND more. But since it is the same operator, the number of chains formed with identical operators does not change.

b := b1 AND b2 OR b3;                //+2: one chain of AND operators and one chain of OR operators

The expression has a chain of AND operators and a chain of OR operators. This results in an increment of 2.


b := b1 AND b2 OR b3 AND b4 AND b5;  //+3: one chain of AND operators, one chain of OR operators and another chain of AND operators

The code snippet has an increment of 3.


b := b1 AND NOT b2 AND b3;           //+1: the unary NOT operator is not considered in the cognitive complexity

The unary operator NOT is not taken into account in the cognitive complexity.

Sample: Further statements with increment

Structured Text has additional statements and expressions that change the control flow.

The following statements are penalized with an increment in cognitive complexity:

aNewLabel:
    x := MUX(i, a,b,c);  //+1 for MUX operator
    y := SEL(b, i,j);    //+1 for SEL operator
JMP aNewLabel;           //+1 for JMP to label

EXIT and RETURN statements do not increase cognitive complexity.