clang-tools-extra/docs/clang-tidy/checks/hicpp/multiway-paths-covered.rst

   1 .. title:: clang-tidy - hicpp-multiway-paths-covered
   2
   3 hicpp-multiway-paths-covered
   4 ============================
   5
   6 This check discovers situations where code paths are not fully-covered.
   7 It furthermore suggests using ``if`` instead of ``switch`` if the code will be more clear.
   8 The `rule 6.1.2 <http://www.codingstandard.com/rule/6-1-2-explicitly-cover-all-paths-through-multi-way-selection-statements/>`_
   9 and `rule 6.1.4 <http://www.codingstandard.com/rule/6-1-4-ensure-that-a-switch-statement-has-at-least-two-case-labels-distinct-from-the-default-label/>`_
  10 of the High Integrity C++ Coding Standard are enforced.
  11
  12 ``if-else if`` chains that miss a final ``else`` branch might lead to unexpected
  13 program execution and be the result of a logical error.
  14 If the missing ``else`` branch is intended you can leave it empty with a clarifying
  15 comment.
  16 This warning can be noisy on some code bases, so it is disabled by default.
  17
  18 .. code-block:: c++
  19
  20   void f1() {
  21     int i = determineTheNumber();
  22
  23      if(i > 0) {
  24        // Some Calculation
  25      } else if (i < 0) {
  26        // Precondition violated or something else.
  27      }
  28      // ...
  29   }
  30
  31 Similar arguments hold for ``switch`` statements which do not cover all possible code paths.
  32
  33 .. code-block:: c++
  34
  35   // The missing default branch might be a logical error. It can be kept empty
  36   // if there is nothing to do, making it explicit.
  37   void f2(int i) {
  38     switch (i) {
  39     case 0: // something
  40       break;
  41     case 1: // something else
  42       break;
  43     }
  44     // All other numbers?
  45   }
  46
  47   // Violates this rule as well, but already emits a compiler warning (-Wswitch).
  48   enum Color { Red, Green, Blue, Yellow };
  49   void f3(enum Color c) {
  50     switch (c) {
  51     case Red: // We can't drive for now.
  52       break;
  53     case Green:  // We are allowed to drive.
  54       break;
  55     }
  56     // Other cases missing
  57   }
  58
  59
  60 The `rule 6.1.4 <http://www.codingstandard.com/rule/6-1-4-ensure-that-a-switch-statement-has-at-least-two-case-labels-distinct-from-the-default-label/>`_
  61 requires every ``switch`` statement to have at least two ``case`` labels other than a `default` label.
  62 Otherwise, the ``switch`` could be better expressed with an ``if`` statement.
  63 Degenerated ``switch`` statements without any labels are caught as well.
  64
  65 .. code-block:: c++
  66
  67   // Degenerated switch that could be better written as `if`
  68   int i = 42;
  69   switch(i) {
  70     case 1: // do something here
  71     default: // do something else here
  72   }
  73
  74   // Should rather be the following:
  75   if (i == 1) {
  76     // do something here
  77   }
  78   else {
  79     // do something here
  80   }
  81
  82
  83 .. code-block:: c++
  84
  85   // A completely degenerated switch will be diagnosed.
  86   int i = 42;
  87   switch(i) {}
  88
  89
  90 Options
  91 -------
  92
  93 .. option:: WarnOnMissingElse
  94
  95   Boolean flag that activates a warning for missing ``else`` branches.
  96   Default is `false`.