eslint/docs/rules/nonblock-statement-body-position.md

   1 # enforce the location of single-line statements (nonblock-statement-body-position)
   2
   3 When writing `if`, `else`, `while`, `do-while`, and `for` statements, the body can be a single statement instead of a block. It can be useful to enforce a consistent location for these single statements.
   4
   5 For example, some developers avoid writing code like this:
   6
   7 ```js
   8 if (foo)
   9   bar();
  10 ```
  11
  12 If another developer attempts to add `baz();` to the `if` statement, they might mistakenly change the code to
  13
  14 ```js
  15 if (foo)
  16   bar();
  17   baz(); // this line is not in the `if` statement!
  18 ```
  19
  20 To avoid this issue, one might require all single-line `if` statements to appear directly after the conditional, without a linebreak:
  21
  22 ```js
  23 if (foo) bar();
  24 ```
  25
  26 ## Rule Details
  27
  28 This rule aims to enforce a consistent location for single-line statements.
  29
  30 Note that this rule does not enforce the usage of single-line statements in general. If you would like to disallow single-line statements, use the [`curly`](/docs/rules/curly.md) rule instead.
  31
  32 ### Options
  33
  34 This rule accepts a string option:
  35
  36 * `"beside"` (default) disallows a newline before a single-line statement.
  37 * `"below"` requires a newline before a single-line statement.
  38 * `"any"` does not enforce the position of a single-line statement.
  39
  40 Additionally, the rule accepts an optional object option with an `"overrides"` key. This can be used to specify a location for particular statements that override the default. For example:
  41
  42 * `"beside", { "overrides": { "while": "below" } }` requires all single-line statements to appear on the same line as their parent, unless the parent is a `while` statement, in which case the single-line statement must not be on the same line.
  43 * `"below", { "overrides": { "do": "any" } }` disallows all single-line statements from appearing on the same line as their parent, unless the parent is a `do-while` statement, in which case the position of the single-line statement is not enforced.
  44
  45 Examples of **incorrect** code for this rule with the default `"beside"` option:
  46
  47 ```js
  48 /* eslint nonblock-statement-body-position: ["error", "beside"] */
  49
  50 if (foo)
  51   bar();
  52 else
  53   baz();
  54
  55 while (foo)
  56   bar();
  57
  58 for (let i = 1; i < foo; i++)
  59   bar();
  60
  61 do
  62   bar();
  63 while (foo)
  64
  65 ```
  66
  67 Examples of **correct** code for this rule with the default `"beside"` option:
  68
  69 ```js
  70 /* eslint nonblock-statement-body-position: ["error", "beside"] */
  71
  72 if (foo) bar();
  73 else baz();
  74
  75 while (foo) bar();
  76
  77 for (let i = 1; i < foo; i++) bar();
  78
  79 do bar(); while (foo)
  80
  81 if (foo) { // block statements are always allowed with this rule
  82   bar();
  83 } else {
  84   baz();
  85 }
  86 ```
  87
  88 Examples of **incorrect** code for this rule with the `"below"` option:
  89
  90 ```js
  91 /* eslint nonblock-statement-body-position: ["error", "below"] */
  92
  93 if (foo) bar();
  94 else baz();
  95
  96 while (foo) bar();
  97
  98 for (let i = 1; i < foo; i++) bar();
  99
 100 do bar(); while (foo)
 101 ```
 102
 103 Examples of **correct** code for this rule with the `"below"` option:
 104
 105 ```js
 106 /* eslint nonblock-statement-body-position: ["error", "below"] */
 107
 108 if (foo)
 109   bar();
 110 else
 111   baz();
 112
 113 while (foo)
 114   bar();
 115
 116 for (let i = 1; i < foo; i++)
 117   bar();
 118
 119 do
 120   bar();
 121 while (foo)
 122
 123 if (foo) {
 124   // Although the second `if` statement is on the same line as the `else`, this is a very common
 125   // pattern, so it's not checked by this rule.
 126 } else if (bar) {
 127 }
 128 ```
 129
 130 Examples of **incorrect** code for this rule with the `"beside", { "overrides": { "while": "below" } }` rule:
 131
 132 ```js
 133 /* eslint nonblock-statement-body-position: ["error", "beside", { "overrides": { "while": "below" } }] */
 134
 135 if (foo)
 136   bar();
 137
 138 while (foo) bar();
 139 ```
 140
 141 Examples of **correct** code for this rule with the `"beside", { "overrides": { "while": "below" } }` rule:
 142
 143 ```js
 144 /* eslint nonblock-statement-body-position: ["error", "beside", { "overrides": { "while": "below" } }] */
 145
 146 if (foo) bar();
 147
 148 while (foo)
 149   bar();
 150 ```
 151
 152 ## When Not To Use It
 153
 154 If you're not concerned about consistent locations of single-line statements, you should not turn on this rule. You can also disable this rule if you're using the `"all"` option for the [`curly`](/docs/rules/curly.md) rule, because this will disallow single-line statements entirely.
 155
 156 ## Further Reading
 157
 158 * JSCS: [requireNewlineBeforeSingleStatementsInIf](https://jscs-dev.github.io/rule/requireNewlineBeforeSingleStatementsInIf)