| 1 |
.. title:: clang-tidy - readability-magic-numbers |
| 2 |
|
| 3 |
readability-magic-numbers |
| 4 |
========================= |
| 5 |
|
| 6 |
Detects magic numbers, integer or floating point literals that are embedded in |
| 7 |
code and not introduced via constants or symbols. |
| 8 |
|
| 9 |
Many coding guidelines advise replacing the magic values with symbolic |
| 10 |
constants to improve readability. Here are a few references: |
| 11 |
|
| 12 |
* `Rule ES.45: Avoid "magic constants"; use symbolic constants in C++ Core Guidelines <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-magic>`_ |
| 13 |
* `Rule 5.1.1 Use symbolic names instead of literal values in code in High Integrity C++ <http://www.codingstandard.com/rule/5-1-1-use-symbolic-names-instead-of-literal-values-in-code/>`_ |
| 14 |
* Item 17 in "C++ Coding Standards: 101 Rules, Guidelines and Best |
| 15 |
Practices" by Herb Sutter and Andrei Alexandrescu |
| 16 |
* Chapter 17 in "Clean Code - A handbook of agile software craftsmanship." |
| 17 |
by Robert C. Martin |
| 18 |
* Rule 20701 in "TRAIN REAL TIME DATA PROTOCOL Coding Rules" by Armin-Hagen |
| 19 |
Weiss, Bombardier |
| 20 |
* http://wiki.c2.com/?MagicNumber |
| 21 |
|
| 22 |
|
| 23 |
Examples of magic values: |
| 24 |
|
| 25 |
.. code-block:: c++ |
| 26 |
|
| 27 |
double circleArea = 3.1415926535 * radius * radius; |
| 28 |
|
| 29 |
double totalCharge = 1.08 * itemPrice; |
| 30 |
|
| 31 |
int getAnswer() { |
| 32 |
return -3; // FILENOTFOUND |
| 33 |
} |
| 34 |
|
| 35 |
for (int mm = 1; mm <= 12; ++mm) { |
| 36 |
std::cout << month[mm] << '\n'; |
| 37 |
} |
| 38 |
|
| 39 |
Example with magic values refactored: |
| 40 |
|
| 41 |
.. code-block:: c++ |
| 42 |
|
| 43 |
double circleArea = M_PI * radius * radius; |
| 44 |
|
| 45 |
const double TAX_RATE = 0.08; // or make it variable and read from a file |
| 46 |
|
| 47 |
double totalCharge = (1.0 + TAX_RATE) * itemPrice; |
| 48 |
|
| 49 |
int getAnswer() { |
| 50 |
return E_FILE_NOT_FOUND; |
| 51 |
} |
| 52 |
|
| 53 |
for (int mm = 1; mm <= MONTHS_IN_A_YEAR; ++mm) { |
| 54 |
std::cout << month[mm] << '\n'; |
| 55 |
} |
| 56 |
|
| 57 |
For integral literals by default only `0` and `1` (and `-1`) integer values |
| 58 |
are accepted without a warning. This can be overridden with the |
| 59 |
:option:`IgnoredIntegerValues` option. Negative values are accepted if their |
| 60 |
absolute value is present in the :option:`IgnoredIntegerValues` list. |
| 61 |
|
| 62 |
As a special case for integral values, all powers of two can be accepted |
| 63 |
without warning by enabling the :option:`IgnorePowersOf2IntegerValues` option. |
| 64 |
|
| 65 |
For floating point literals by default the `0.0` floating point value is |
| 66 |
accepted without a warning. The set of ignored floating point literals can |
| 67 |
be configured using the :option:`IgnoredFloatingPointValues` option. |
| 68 |
For each value in that set, the given string value is converted to a |
| 69 |
floating-point value representation used by the target architecture. If a |
| 70 |
floating-point literal value compares equal to one of the converted values, |
| 71 |
then that literal is not diagnosed by this check. Because floating-point |
| 72 |
equality is used to determine whether to diagnose or not, the user needs to |
| 73 |
be aware of the details of floating-point representations for any values that |
| 74 |
cannot be precisely represented for their target architecture. |
| 75 |
|
| 76 |
For each value in the :option:`IgnoredFloatingPointValues` set, both the |
| 77 |
single-precision form and double-precision form are accepted (for example, if |
| 78 |
3.14 is in the set, neither 3.14f nor 3.14 will produce a warning). |
| 79 |
|
| 80 |
Scientific notation is supported for both source code input and option. |
| 81 |
Alternatively, the check for the floating point numbers can be disabled for |
| 82 |
all floating point values by enabling the |
| 83 |
:option:`IgnoreAllFloatingPointValues` option. |
| 84 |
|
| 85 |
Since values `0` and `0.0` are so common as the base counter of loops, |
| 86 |
or initialization values for sums, they are always accepted without warning, |
| 87 |
even if not present in the respective ignored values list. |
| 88 |
|
| 89 |
Options |
| 90 |
------- |
| 91 |
|
| 92 |
.. option:: IgnoredIntegerValues |
| 93 |
|
| 94 |
Semicolon-separated list of magic positive integers that will be accepted |
| 95 |
without a warning. Default values are `{1, 2, 3, 4}`, and `0` is accepted |
| 96 |
unconditionally. |
| 97 |
|
| 98 |
.. option:: IgnorePowersOf2IntegerValues |
| 99 |
|
| 100 |
Boolean value indicating whether to accept all powers-of-two integer values |
| 101 |
without warning. Default value is `false`. |
| 102 |
|
| 103 |
.. option:: IgnoredFloatingPointValues |
| 104 |
|
| 105 |
Semicolon-separated list of magic positive floating point values that will |
| 106 |
be accepted without a warning. Default values are `{1.0, 100.0}` and `0.0` |
| 107 |
is accepted unconditionally. |
| 108 |
|
| 109 |
.. option:: IgnoreAllFloatingPointValues |
| 110 |
|
| 111 |
Boolean value indicating whether to accept all floating point values without |
| 112 |
warning. Default value is `false`. |
| 113 |
|
| 114 |
.. option:: IgnoreBitFieldsWidths |
| 115 |
|
| 116 |
Boolean value indicating whether to accept magic numbers as bit field widths |
| 117 |
without warning. This is useful for example for register definitions which |
| 118 |
are generated from hardware specifications. Default value is `true`. |