eslint/docs/src/rules/curly.md

   1 ---
   2 title: curly
   3 layout: doc
   4 rule_type: suggestion
   5 ---
   6
   7
   8
   9 JavaScript allows the omission of curly braces when a block contains only one statement. However, it is considered by many to be best practice to _never_ omit curly braces around blocks, even when they are optional, because it can lead to bugs and reduces code clarity. So the following:
  10
  11 ```js
  12 if (foo) foo++;
  13 ```
  14
  15 Can be rewritten as:
  16
  17 ```js
  18 if (foo) {
  19     foo++;
  20 }
  21 ```
  22
  23 There are, however, some who prefer to only use braces when there is more than one statement to be executed.
  24
  25 ## Rule Details
  26
  27 This rule is aimed at preventing bugs and increasing code clarity by ensuring that block statements are wrapped in curly braces. It will warn when it encounters blocks that omit curly braces.
  28
  29 ## Options
  30
  31 ### all
  32
  33 Examples of **incorrect** code for the default `"all"` option:
  34
  35 ::: incorrect
  36
  37 ```js
  38 /*eslint curly: "error"*/
  39
  40 if (foo) foo++;
  41
  42 while (bar)
  43     baz();
  44
  45 if (foo) {
  46     baz();
  47 } else qux();
  48 ```
  49
  50 :::
  51
  52 Examples of **correct** code for the default `"all"` option:
  53
  54 ::: correct
  55
  56 ```js
  57 /*eslint curly: "error"*/
  58
  59 if (foo) {
  60     foo++;
  61 }
  62
  63 while (bar) {
  64     baz();
  65 }
  66
  67 if (foo) {
  68     baz();
  69 } else {
  70     qux();
  71 }
  72 ```
  73
  74 :::
  75
  76 ### multi
  77
  78 By default, this rule warns whenever `if`, `else`, `for`, `while`, or `do` are used without block statements as their body. However, you can specify that block statements should be used only when there are multiple statements in the block and warn when there is only one statement in the block.
  79
  80 Examples of **incorrect** code for the `"multi"` option:
  81
  82 ::: incorrect
  83
  84 ```js
  85 /*eslint curly: ["error", "multi"]*/
  86
  87 if (foo) {
  88     foo++;
  89 }
  90
  91 if (foo) bar();
  92 else {
  93     foo++;
  94 }
  95
  96 while (true) {
  97     doSomething();
  98 }
  99
 100 for (var i=0; i < items.length; i++) {
 101     doSomething();
 102 }
 103 ```
 104
 105 :::
 106
 107 Examples of **correct** code for the `"multi"` option:
 108
 109 ::: correct
 110
 111 ```js
 112 /*eslint curly: ["error", "multi"]*/
 113
 114 if (foo) foo++;
 115
 116 else foo();
 117
 118 while (true) {
 119     doSomething();
 120     doSomethingElse();
 121 }
 122 ```
 123
 124 :::
 125
 126 ### multi-line
 127
 128 Alternatively, you can relax the rule to allow brace-less single-line `if`, `else if`, `else`, `for`, `while`, or `do`, while still enforcing the use of curly braces for other instances.
 129
 130 Examples of **incorrect** code for the `"multi-line"` option:
 131
 132 ::: incorrect
 133
 134 ```js
 135 /*eslint curly: ["error", "multi-line"]*/
 136
 137 if (foo)
 138   doSomething();
 139 else
 140   doSomethingElse();
 141
 142 if (foo) foo(
 143   bar,
 144   baz);
 145 ```
 146
 147 :::
 148
 149 Examples of **correct** code for the `"multi-line"` option:
 150
 151 ::: correct
 152
 153 ```js
 154 /*eslint curly: ["error", "multi-line"]*/
 155
 156 if (foo) foo++; else doSomething();
 157
 158 if (foo) foo++;
 159 else if (bar) baz()
 160 else doSomething();
 161
 162 do something();
 163 while (foo);
 164
 165 while (foo
 166   && bar) baz();
 167
 168 if (foo) {
 169     foo++;
 170 }
 171
 172 if (foo) { foo++; }
 173
 174 while (true) {
 175     doSomething();
 176     doSomethingElse();
 177 }
 178 ```
 179
 180 :::
 181
 182 ### multi-or-nest
 183
 184 You can use another configuration that forces brace-less `if`, `else if`, `else`, `for`, `while`, or `do` if their body contains only one single-line statement. And forces braces in all other cases.
 185
 186 Examples of **incorrect** code for the `"multi-or-nest"` option:
 187
 188 ::: incorrect
 189
 190 ```js
 191 /*eslint curly: ["error", "multi-or-nest"]*/
 192
 193 if (!foo)
 194     foo = {
 195         bar: baz,
 196         qux: foo
 197     };
 198
 199 while (true)
 200   if(foo)
 201       doSomething();
 202   else
 203       doSomethingElse();
 204
 205 if (foo) {
 206     foo++;
 207 }
 208
 209 while (true) {
 210     doSomething();
 211 }
 212
 213 for (var i = 0; foo; i++) {
 214     doSomething();
 215 }
 216 ```
 217
 218 :::
 219
 220 Examples of **correct** code for the `"multi-or-nest"` option:
 221
 222 ::: correct
 223
 224 ```js
 225 /*eslint curly: ["error", "multi-or-nest"]*/
 226
 227 if (!foo) {
 228     foo = {
 229         bar: baz,
 230         qux: foo
 231     };
 232 }
 233
 234 while (true) {
 235   if(foo)
 236       doSomething();
 237   else
 238       doSomethingElse();
 239 }
 240
 241 if (foo)
 242     foo++;
 243
 244 while (true)
 245     doSomething();
 246
 247 for (var i = 0; foo; i++)
 248     doSomething();
 249 ```
 250
 251 :::
 252
 253 For single-line statements preceded by a comment, braces are allowed but not required.
 254
 255 Examples of additional **correct** code for the `"multi-or-nest"` option:
 256
 257 ::: correct
 258
 259 ```js
 260 /*eslint curly: ["error", "multi-or-nest"]*/
 261
 262 if (foo)
 263     // some comment
 264     bar();
 265
 266 if (foo) {
 267     // some comment
 268     bar();
 269 }
 270 ```
 271
 272 :::
 273
 274 ### consistent
 275
 276 When using any of the `multi*` options, you can add an option to enforce all bodies of a `if`,
 277 `else if` and `else` chain to be with or without braces.
 278
 279 Examples of **incorrect** code for the `"multi", "consistent"` options:
 280
 281 ::: incorrect
 282
 283 ```js
 284 /*eslint curly: ["error", "multi", "consistent"]*/
 285
 286 if (foo) {
 287     bar();
 288     baz();
 289 } else
 290     buz();
 291
 292 if (foo)
 293     bar();
 294 else if (faa)
 295     bor();
 296 else {
 297     other();
 298     things();
 299 }
 300
 301 if (true)
 302     foo();
 303 else {
 304     baz();
 305 }
 306
 307 if (foo) {
 308     foo++;
 309 }
 310 ```
 311
 312 :::
 313
 314 Examples of **correct** code for the `"multi", "consistent"` options:
 315
 316 ::: correct
 317
 318 ```js
 319 /*eslint curly: ["error", "multi", "consistent"]*/
 320
 321 if (foo) {
 322     bar();
 323     baz();
 324 } else {
 325     buz();
 326 }
 327
 328 if (foo) {
 329     bar();
 330 } else if (faa) {
 331     bor();
 332 } else {
 333     other();
 334     things();
 335 }
 336
 337 if (true)
 338     foo();
 339 else
 340     baz();
 341
 342 if (foo)
 343     foo++;
 344
 345 ```
 346
 347 :::
 348
 349 ## When Not To Use It
 350
 351 If you have no strict conventions about when to use block statements and when not to, you can safely disable this rule.