eslint/docs/rules/no-return-assign.md

   1 # Disallow Assignment in return Statement (no-return-assign)
   2
   3 One of the interesting, and sometimes confusing, aspects of JavaScript is that assignment can happen at almost any point. Because of this, an errant equals sign can end up causing assignment when the true intent was to do a comparison. This is especially true when using a `return` statement. For example:
   4
   5 ```js
   6 function doSomething() {
   7     return foo = bar + 2;
   8 }
   9 ```
  10
  11 It is difficult to tell the intent of the `return` statement here. It's possible that the function is meant to return the result of `bar + 2`, but then why is it assigning to `foo`? It's also possible that the intent was to use a comparison operator such as `==` and that this code is an error.
  12
  13 Because of this ambiguity, it's considered a best practice to not use assignment in `return` statements.
  14
  15 ## Rule Details
  16
  17 This rule aims to eliminate assignments from `return` statements. As such, it will warn whenever an assignment is found as part of `return`.
  18
  19 ## Options
  20
  21 The rule takes one option, a string, which must contain one of the following values:
  22
  23 * `except-parens` (default): Disallow assignments unless they are enclosed in parentheses.
  24 * `always`: Disallow all assignments.
  25
  26 ### except-parens
  27
  28 This is the default option.
  29 It disallows assignments unless they are enclosed in parentheses.
  30
  31 Examples of **incorrect** code for the default `"except-parens"` option:
  32
  33 ```js
  34 /*eslint no-return-assign: "error"*/
  35
  36 function doSomething() {
  37     return foo = bar + 2;
  38 }
  39
  40 function doSomething() {
  41     return foo += 2;
  42 }
  43
  44 const foo = (a, b) => a = b
  45
  46 const bar = (a, b, c) => (a = b, c == b)
  47
  48 function doSomething() {
  49     return foo = bar && foo > 0;
  50 }
  51 ```
  52
  53 Examples of **correct** code for the default `"except-parens"` option:
  54
  55 ```js
  56 /*eslint no-return-assign: "error"*/
  57
  58 function doSomething() {
  59     return foo == bar + 2;
  60 }
  61
  62 function doSomething() {
  63     return foo === bar + 2;
  64 }
  65
  66 function doSomething() {
  67     return (foo = bar + 2);
  68 }
  69
  70 const foo = (a, b) => (a = b)
  71
  72 const bar = (a, b, c) => ((a = b), c == b)
  73
  74 function doSomething() {
  75     return (foo = bar) && foo > 0;
  76 }
  77 ```
  78
  79 ### always
  80
  81 This option disallows all assignments in `return` statements.
  82 All assignments are treated as problems.
  83
  84 Examples of **incorrect** code for the `"always"` option:
  85
  86 ```js
  87 /*eslint no-return-assign: ["error", "always"]*/
  88
  89 function doSomething() {
  90     return foo = bar + 2;
  91 }
  92
  93 function doSomething() {
  94     return foo += 2;
  95 }
  96
  97 function doSomething() {
  98     return (foo = bar + 2);
  99 }
 100 ```
 101
 102 Examples of **correct** code for the `"always"` option:
 103
 104 ```js
 105 /*eslint no-return-assign: ["error", "always"]*/
 106
 107 function doSomething() {
 108     return foo == bar + 2;
 109 }
 110
 111 function doSomething() {
 112     return foo === bar + 2;
 113 }
 114 ```
 115
 116 ## When Not To Use It
 117
 118 If you want to allow the use of assignment operators in a `return` statement, then you can safely disable this rule.