clang-tools-extra/docs/clang-tidy/checks/readability/function-cognitive-complexity.rst

   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.