| 1 |
.. title:: clang-tidy - readability-function-cognitive-complexity |
| 2 |
|
| 3 |
readability-function-cognitive-complexity |
| 4 |
========================================= |
| 5 |
|
| 6 |
Checks function Cognitive Complexity metric. |
| 7 |
|
| 8 |
The metric is implemented as per the `COGNITIVE COMPLEXITY by SonarSource |
| 9 |
<https://www.sonarsource.com/docs/CognitiveComplexity.pdf>`_ specification |
| 10 |
version 1.2 (19 April 2017). |
| 11 |
|
| 12 |
Options |
| 13 |
------- |
| 14 |
|
| 15 |
.. option:: Threshold |
| 16 |
|
| 17 |
Flag functions with Cognitive Complexity exceeding this number. |
| 18 |
The default is `25`. |
| 19 |
|
| 20 |
.. option:: DescribeBasicIncrements |
| 21 |
|
| 22 |
If set to `true`, then for each function exceeding the complexity threshold |
| 23 |
the check will issue additional diagnostics on every piece of code (loop, |
| 24 |
`if` statement, etc.) which contributes to that complexity. See also the |
| 25 |
examples below. Default is `true`. |
| 26 |
|
| 27 |
.. option:: IgnoreMacros |
| 28 |
|
| 29 |
If set to `true`, the check will ignore code inside macros. Note, that also |
| 30 |
any macro arguments are ignored, even if they should count to the complexity. |
| 31 |
As this might change in the future, this option isn't guaranteed to be |
| 32 |
forward-compatible. Default is `false`. |
| 33 |
|
| 34 |
Building blocks |
| 35 |
--------------- |
| 36 |
|
| 37 |
There are three basic building blocks of a Cognitive Complexity metric: |
| 38 |
|
| 39 |
Increment |
| 40 |
^^^^^^^^^ |
| 41 |
|
| 42 |
The following structures increase the function's Cognitive Complexity metric |
| 43 |
(by `1`): |
| 44 |
|
| 45 |
* Conditional operators: |
| 46 |
|
| 47 |
- ``if()`` |
| 48 |
- ``else if()`` |
| 49 |
- ``else`` |
| 50 |
- ``cond ? true : false`` |
| 51 |
|
| 52 |
* ``switch()`` |
| 53 |
* Loops: |
| 54 |
|
| 55 |
- ``for()`` |
| 56 |
- C++11 range-based ``for()`` |
| 57 |
- ``while()`` |
| 58 |
- ``do while()`` |
| 59 |
|
| 60 |
* ``catch ()`` |
| 61 |
* ``goto LABEL``, ``goto *(&&LABEL))``, |
| 62 |
* sequences of binary logical operators: |
| 63 |
|
| 64 |
- ``boolean1 || boolean2`` |
| 65 |
- ``boolean1 && boolean2`` |
| 66 |
|
| 67 |
Nesting level |
| 68 |
^^^^^^^^^^^^^ |
| 69 |
|
| 70 |
While by itself the nesting level does not change the function's Cognitive |
| 71 |
Complexity metric, it is tracked, and is used by the next, third building block. |
| 72 |
The following structures increase the nesting level (by `1`): |
| 73 |
|
| 74 |
* Conditional operators: |
| 75 |
|
| 76 |
- ``if()`` |
| 77 |
- ``else if()`` |
| 78 |
- ``else`` |
| 79 |
- ``cond ? true : false`` |
| 80 |
|
| 81 |
* ``switch()`` |
| 82 |
* Loops: |
| 83 |
|
| 84 |
- ``for()`` |
| 85 |
- C++11 range-based ``for()`` |
| 86 |
- ``while()`` |
| 87 |
- ``do while()`` |
| 88 |
|
| 89 |
* ``catch ()`` |
| 90 |
* Nested functions: |
| 91 |
|
| 92 |
- C++11 Lambda |
| 93 |
- Nested ``class`` |
| 94 |
- Nested ``struct`` |
| 95 |
* GNU statement expression |
| 96 |
* Apple Block Declaration |
| 97 |
|
| 98 |
Nesting increment |
| 99 |
^^^^^^^^^^^^^^^^^ |
| 100 |
|
| 101 |
This is where the previous basic building block, `Nesting level`_, matters. |
| 102 |
The following structures increase the function's Cognitive Complexity metric by |
| 103 |
the current `Nesting level`_: |
| 104 |
|
| 105 |
* Conditional operators: |
| 106 |
|
| 107 |
- ``if()`` |
| 108 |
- ``cond ? true : false`` |
| 109 |
|
| 110 |
* ``switch()`` |
| 111 |
* Loops: |
| 112 |
|
| 113 |
- ``for()`` |
| 114 |
- C++11 range-based ``for()`` |
| 115 |
- ``while()`` |
| 116 |
- ``do while()`` |
| 117 |
|
| 118 |
* ``catch ()`` |
| 119 |
|
| 120 |
Examples |
| 121 |
-------- |
| 122 |
|
| 123 |
The simplest case. This function has Cognitive Complexity of `0`. |
| 124 |
|
| 125 |
.. code-block:: c++ |
| 126 |
|
| 127 |
void function0() {} |
| 128 |
|
| 129 |
Slightly better example. This function has Cognitive Complexity of `1`. |
| 130 |
|
| 131 |
.. code-block:: c++ |
| 132 |
|
| 133 |
int function1(bool var) { |
| 134 |
if(var) // +1, nesting level +1 |
| 135 |
return 42; |
| 136 |
return 0; |
| 137 |
} |
| 138 |
|
| 139 |
Full example. This function has Cognitive Complexity of `3`. |
| 140 |
|
| 141 |
.. code-block:: c++ |
| 142 |
|
| 143 |
int function3(bool var1, bool var2) { |
| 144 |
if(var1) { // +1, nesting level +1 |
| 145 |
if(var2) // +2 (1 + current nesting level of 1), nesting level +1 |
| 146 |
return 42; |
| 147 |
} |
| 148 |
|
| 149 |
return 0; |
| 150 |
} |
| 151 |
|
| 152 |
In the last example, the check will flag `function3` if the option Threshold is |
| 153 |
set to `2` or smaller. If the option DescribeBasicIncrements is set to `true`, |
| 154 |
it will additionally flag the two `if` statements with the amounts by which they |
| 155 |
increase to the complexity of the function and the current nesting level. |
| 156 |
|
| 157 |
Limitations |
| 158 |
----------- |
| 159 |
|
| 160 |
The metric is implemented with two notable exceptions: |
| 161 |
* `preprocessor conditionals` (``#ifdef``, ``#if``, ``#elif``, ``#else``, |
| 162 |
``#endif``) are not accounted for. |
| 163 |
* `each method in a recursion cycle` is not accounted for. It can't be fully |
| 164 |
implemented, because cross-translational-unit analysis would be needed, |
| 165 |
which is currently not possible in clang-tidy. |