projects / pve-eslint.git / blame
| Commit | Line | Data |
|---|---|---|
| eb39fafa DC |
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) |