eslint/docs/rules/consistent-return.md

   1 # require `return` statements to either always or never specify values (consistent-return)
   2
   3 Unlike statically-typed languages which enforce that a function returns a specified type of value, JavaScript allows different code paths in a function to return different types of values.
   4
   5 A confusing aspect of JavaScript is that a function returns `undefined` if any of the following are true:
   6
   7 * it does not execute a `return` statement before it exits
   8 * it executes `return` which does not specify a value explicitly
   9 * it executes `return undefined`
  10 * it executes `return void` followed by an expression (for example, a function call)
  11 * it executes `return` followed by any other expression which evaluates to `undefined`
  12
  13 If any code paths in a function return a value explicitly but some code path do not return a value explicitly, it might be a typing mistake, especially in a large function. In the following example:
  14
  15 * a code path through the function returns a Boolean value `true`
  16 * another code path does not return a value explicitly, therefore returns `undefined` implicitly
  17
  18 ```js
  19 function doSomething(condition) {
  20     if (condition) {
  21         return true;
  22     } else {
  23         return;
  24     }
  25 }
  26 ```
  27
  28 ## Rule Details
  29
  30 This rule requires `return` statements to either always or never specify values. This rule ignores function definitions where the name begins with an uppercase letter, because constructors (when invoked with the `new` operator) return the instantiated object implicitly if they do not return another object explicitly.
  31
  32 Examples of **incorrect** code for this rule:
  33
  34 ```js
  35 /*eslint consistent-return: "error"*/
  36
  37 function doSomething(condition) {
  38     if (condition) {
  39         return true;
  40     } else {
  41         return;
  42     }
  43 }
  44
  45 function doSomething(condition) {
  46     if (condition) {
  47         return true;
  48     }
  49 }
  50 ```
  51
  52 Examples of **correct** code for this rule:
  53
  54 ```js
  55 /*eslint consistent-return: "error"*/
  56
  57 function doSomething(condition) {
  58     if (condition) {
  59         return true;
  60     } else {
  61         return false;
  62     }
  63 }
  64
  65 function Foo() {
  66     if (!(this instanceof Foo)) {
  67         return new Foo();
  68     }
  69
  70     this.a = 0;
  71 }
  72 ```
  73
  74 ## Options
  75
  76 This rule has an object option:
  77
  78 * `"treatUndefinedAsUnspecified": false` (default) always either specify values or return `undefined` implicitly only.
  79 * `"treatUndefinedAsUnspecified": true` always either specify values or return `undefined` explicitly or implicitly.
  80
  81 ### treatUndefinedAsUnspecified
  82
  83 Examples of **incorrect** code for this rule with the default `{ "treatUndefinedAsUnspecified": false }` option:
  84
  85 ```js
  86 /*eslint consistent-return: ["error", { "treatUndefinedAsUnspecified": false }]*/
  87
  88 function foo(callback) {
  89     if (callback) {
  90         return void callback();
  91     }
  92     // no return statement
  93 }
  94
  95 function bar(condition) {
  96     if (condition) {
  97         return undefined;
  98     }
  99     // no return statement
 100 }
 101 ```
 102
 103 Examples of **incorrect** code for this rule with the `{ "treatUndefinedAsUnspecified": true }` option:
 104
 105 ```js
 106 /*eslint consistent-return: ["error", { "treatUndefinedAsUnspecified": true }]*/
 107
 108 function foo(callback) {
 109     if (callback) {
 110         return void callback();
 111     }
 112     return true;
 113 }
 114
 115 function bar(condition) {
 116     if (condition) {
 117         return undefined;
 118     }
 119     return true;
 120 }
 121 ```
 122
 123 Examples of **correct** code for this rule with the `{ "treatUndefinedAsUnspecified": true }` option:
 124
 125 ```js
 126 /*eslint consistent-return: ["error", { "treatUndefinedAsUnspecified": true }]*/
 127
 128 function foo(callback) {
 129     if (callback) {
 130         return void callback();
 131     }
 132     // no return statement
 133 }
 134
 135 function bar(condition) {
 136     if (condition) {
 137         return undefined;
 138     }
 139     // no return statement
 140 }
 141 ```
 142
 143 ## When Not To Use It
 144
 145 If you want to allow functions to have different `return` behavior depending on code branching, then it is safe to disable this rule.