eslint/docs/rules/no-magic-numbers.md

   1 # Disallow Magic Numbers (no-magic-numbers)
   2
   3 'Magic numbers' are numbers that occur multiple times in code without an explicit meaning.
   4 They should preferably be replaced by named constants.
   5
   6 ```js
   7 var now = Date.now(),
   8     inOneHour = now + (60 * 60 * 1000);
   9 ```
  10
  11 ## Rule Details
  12
  13 The `no-magic-numbers` rule aims to make code more readable and refactoring easier by ensuring that special numbers
  14 are declared as constants to make their meaning explicit.
  15
  16 Examples of **incorrect** code for this rule:
  17
  18 ```js
  19 /*eslint no-magic-numbers: "error"*/
  20
  21 var dutyFreePrice = 100,
  22     finalPrice = dutyFreePrice + (dutyFreePrice * 0.25);
  23 ```
  24
  25 ```js
  26 /*eslint no-magic-numbers: "error"*/
  27
  28 var data = ['foo', 'bar', 'baz'];
  29
  30 var dataLast = data[2];
  31 ```
  32
  33 ```js
  34 /*eslint no-magic-numbers: "error"*/
  35
  36 var SECONDS;
  37
  38 SECONDS = 60;
  39 ```
  40
  41 Examples of **correct** code for this rule:
  42
  43 ```js
  44 /*eslint no-magic-numbers: "error"*/
  45
  46 var TAX = 0.25;
  47
  48 var dutyFreePrice = 100,
  49     finalPrice = dutyFreePrice + (dutyFreePrice * TAX);
  50 ```
  51
  52 ## Options
  53
  54 ### ignore
  55
  56 An array of numbers to ignore. It's set to `[]` by default.
  57 If provided, it must be an `Array`.
  58
  59 The array can contain values of `number` and `string` types.
  60 If it's a string, the text must be parsed as `bigint` literal (e.g., `"100n"`).
  61
  62 Examples of **correct** code for the sample `{ "ignore": [1] }` option:
  63
  64 ```js
  65 /*eslint no-magic-numbers: ["error", { "ignore": [1] }]*/
  66
  67 var data = ['foo', 'bar', 'baz'];
  68 var dataLast = data.length && data[data.length - 1];
  69 ```
  70
  71 Examples of **correct** code for the sample `{ "ignore": ["1n"] }` option:
  72
  73 ```js
  74 /*eslint no-magic-numbers: ["error", { "ignore": ["1n"] }]*/
  75
  76 foo(1n);
  77 ```
  78
  79 ### ignoreArrayIndexes
  80
  81 A boolean to specify if numbers used in the context of array indexes (e.g., `data[2]`) are considered okay. `false` by default.
  82
  83 This option allows only valid array indexes: numbers that will be coerced to one of `"0"`, `"1"`, `"2"` ... `"4294967294"`.
  84
  85 Arrays are objects, so they can have property names such as `"-1"` or `"2.5"`. However, those are just "normal" object properties that don't represent array elements. They don't influence the array's `length`, and they are ignored by array methods like `.map` or `.forEach`.
  86
  87 Additionally, since the maximum [array length](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length) is 2<sup>32</sup> - 1, all values above 2<sup>32</sup> - 2 also represent just normal property names and are thus not considered to be array indexes.
  88
  89 Examples of **correct** code for the `{ "ignoreArrayIndexes": true }` option:
  90
  91 ```js
  92 /*eslint no-magic-numbers: ["error", { "ignoreArrayIndexes": true }]*/
  93
  94 var item = data[2];
  95
  96 data[100] = a;
  97
  98 f(data[0]);
  99
 100 a = data[-0]; // same as data[0], -0 will be coerced to "0"
 101
 102 a = data[0xAB];
 103
 104 a = data[5.6e1];
 105
 106 a = data[10n]; // same as data[10], 10n will be coerced to "10"
 107
 108 a = data[4294967294]; // max array index
 109 ```
 110
 111 Examples of **incorrect** code for the `{ "ignoreArrayIndexes": true }` option:
 112
 113 ```js
 114 /*eslint no-magic-numbers: ["error", { "ignoreArrayIndexes": true }]*/
 115
 116 f(2); // not used as array index
 117
 118 a = data[-1];
 119
 120 a = data[2.5];
 121
 122 a = data[5.67e1];
 123
 124 a = data[-10n];
 125
 126 a = data[4294967295]; // above the max array index
 127
 128 a = data[1e500]; // same as data["Infinity"]
 129 ```
 130
 131 ### enforceConst
 132
 133 A boolean to specify if we should check for the const keyword in variable declaration of numbers. `false` by default.
 134
 135 Examples of **incorrect** code for the `{ "enforceConst": true }` option:
 136
 137 ```js
 138 /*eslint no-magic-numbers: ["error", { "enforceConst": true }]*/
 139
 140 var TAX = 0.25;
 141
 142 var dutyFreePrice = 100,
 143     finalPrice = dutyFreePrice + (dutyFreePrice * TAX);
 144 ```
 145
 146 ### detectObjects
 147
 148 A boolean to specify if we should detect numbers when setting object properties for example. `false` by default.
 149
 150 Examples of **incorrect** code for the `{ "detectObjects": true }` option:
 151
 152 ```js
 153 /*eslint no-magic-numbers: ["error", { "detectObjects": true }]*/
 154
 155 var magic = {
 156   tax: 0.25
 157 };
 158
 159 var dutyFreePrice = 100,
 160     finalPrice = dutyFreePrice + (dutyFreePrice * magic.tax);
 161 ```
 162
 163 Examples of **correct** code for the `{ "detectObjects": true }` option:
 164
 165 ```js
 166 /*eslint no-magic-numbers: ["error", { "detectObjects": true }]*/
 167
 168 var TAX = 0.25;
 169
 170 var magic = {
 171   tax: TAX
 172 };
 173
 174 var dutyFreePrice = 100,
 175     finalPrice = dutyFreePrice + (dutyFreePrice * magic.tax);
 176 ```