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