eslint/docs/src/rules/func-style.md

   1 ---
   2 title: func-style
   3 layout: doc
   4 rule_type: suggestion
   5 further_reading:
   6 - https://www.adequatelygood.com/JavaScript-Scoping-and-Hoisting.html
   7 ---
   8
   9
  10 There are two ways of defining functions in JavaScript: `function` declarations and `function` expressions. Declarations contain the `function` keyword first, followed by a name and then its arguments and the function body, for example:
  11
  12 ```js
  13 function doSomething() {
  14     // ...
  15 }
  16 ```
  17
  18 Equivalent function expressions begin with the `var` keyword, followed by a name and then the function itself, such as:
  19
  20 ```js
  21 var doSomething = function() {
  22     // ...
  23 };
  24 ```
  25
  26 The primary difference between `function` declarations and `function expressions` is that declarations are *hoisted* to the top of the scope in which they are defined, which allows you to write code that uses the function before its declaration. For example:
  27
  28 ```js
  29 doSomething();
  30
  31 function doSomething() {
  32     // ...
  33 }
  34 ```
  35
  36 Although this code might seem like an error, it actually works fine because JavaScript engines hoist the `function` declarations to the top of the scope. That means this code is treated as if the declaration came before the invocation.
  37
  38 For `function` expressions, you must define the function before it is used, otherwise it causes an error. Example:
  39
  40 ```js
  41 doSomething();  // error!
  42
  43 var doSomething = function() {
  44     // ...
  45 };
  46 ```
  47
  48 In this case, `doSomething()` is undefined at the time of invocation and so causes a runtime error.
  49
  50 Due to these different behaviors, it is common to have guidelines as to which style of function should be used. There is really no correct or incorrect choice here, it is just a preference.
  51
  52 ## Rule Details
  53
  54 This rule enforces a particular type of `function` style throughout a JavaScript file, either declarations or expressions. You can specify which you prefer in the configuration.
  55
  56 ## Options
  57
  58 This rule has a string option:
  59
  60 * `"expression"` (default) requires the use of function expressions instead of function declarations
  61 * `"declaration"` requires the use of function declarations instead of function expressions
  62
  63 This rule has an object option for an exception:
  64
  65 * `"allowArrowFunctions"`: `true` (default `false`) allows the use of arrow functions. This option applies only when the string option is set to `"declaration"` (arrow functions are always allowed when the string option is set to `"expression"`, regardless of this option)
  66
  67 ### expression
  68
  69 Examples of **incorrect** code for this rule with the default `"expression"` option:
  70
  71 ::: incorrect
  72
  73 ```js
  74 /*eslint func-style: ["error", "expression"]*/
  75
  76 function foo() {
  77     // ...
  78 }
  79 ```
  80
  81 :::
  82
  83 Examples of **correct** code for this rule with the default `"expression"` option:
  84
  85 ::: correct
  86
  87 ```js
  88 /*eslint func-style: ["error", "expression"]*/
  89
  90 var foo = function() {
  91     // ...
  92 };
  93
  94 var foo = () => {};
  95
  96 // allowed as allowArrowFunctions : false is applied only for declaration
  97 ```
  98
  99 :::
 100
 101 ### declaration
 102
 103 Examples of **incorrect** code for this rule with the `"declaration"` option:
 104
 105 ::: incorrect
 106
 107 ```js
 108 /*eslint func-style: ["error", "declaration"]*/
 109
 110 var foo = function() {
 111     // ...
 112 };
 113
 114 var foo = () => {};
 115 ```
 116
 117 :::
 118
 119 Examples of **correct** code for this rule with the `"declaration"` option:
 120
 121 ::: correct
 122
 123 ```js
 124 /*eslint func-style: ["error", "declaration"]*/
 125
 126 function foo() {
 127     // ...
 128 }
 129
 130 // Methods (functions assigned to objects) are not checked by this rule
 131 SomeObject.foo = function() {
 132     // ...
 133 };
 134 ```
 135
 136 :::
 137
 138 ### allowArrowFunctions
 139
 140 Examples of additional **correct** code for this rule with the `"declaration", { "allowArrowFunctions": true }` options:
 141
 142 ::: correct
 143
 144 ```js
 145 /*eslint func-style: ["error", "declaration", { "allowArrowFunctions": true }]*/
 146
 147 var foo = () => {};
 148 ```
 149
 150 :::
 151
 152 ## When Not To Use It
 153
 154 If you want to allow developers to each decide how they want to write functions on their own, then you can disable this rule.