eslint/docs/rules/lines-around-comment.md

   1 # require empty lines around comments (lines-around-comment)
   2
   3 Many style guides require empty lines before or after comments. The primary goal
   4 of these rules is to make the comments easier to read and improve readability of the code.
   5
   6 ## Rule Details
   7
   8 This rule requires empty lines before and/or after comments. It can be enabled separately for both block (`/*`) and line (`//`) comments. This rule does not apply to comments that appear on the same line as code and does not require empty lines at the beginning or end of a file.
   9
  10 ## Options
  11
  12 This rule has an object option:
  13
  14 * `"beforeBlockComment": true` (default) requires an empty line before block comments
  15 * `"afterBlockComment": true` requires an empty line after block comments
  16 * `"beforeLineComment": true` requires an empty line before line comments
  17 * `"afterLineComment": true` requires an empty line after line comments
  18 * `"allowBlockStart": true` allows comments to appear at the start of block statements, function bodies, classes, and class static blocks
  19 * `"allowBlockEnd": true` allows comments to appear at the end of block statements, function bodies, classes, and class static blocks
  20 * `"allowObjectStart": true` allows comments to appear at the start of object literals
  21 * `"allowObjectEnd": true` allows comments to appear at the end of object literals
  22 * `"allowArrayStart": true` allows comments to appear at the start of array literals
  23 * `"allowArrayEnd": true` allows comments to appear at the end of array literals
  24 * `"allowClassStart": true` allows comments to appear at the start of classes
  25 * `"allowClassEnd": true` allows comments to appear at the end of classes
  26 * `"applyDefaultIgnorePatterns"` enables or disables the default comment patterns to be ignored by the rule
  27 * `"ignorePattern"` custom patterns to be ignored by the rule
  28
  29
  30 ### beforeBlockComment
  31
  32 Examples of **incorrect** code for this rule with the default `{ "beforeBlockComment": true }` option:
  33
  34 ```js
  35 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true }]*/
  36
  37 var night = "long";
  38 /* what a great and wonderful day */
  39 var day = "great"
  40 ```
  41
  42 Examples of **correct** code for this rule with the default `{ "beforeBlockComment": true }` option:
  43
  44 ```js
  45 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true }]*/
  46
  47 var night = "long";
  48
  49 /* what a great and wonderful day */
  50 var day = "great"
  51 ```
  52
  53 ### afterBlockComment
  54
  55 Examples of **incorrect** code for this rule with the `{ "afterBlockComment": true }` option:
  56
  57 ```js
  58 /*eslint lines-around-comment: ["error", { "afterBlockComment": true }]*/
  59
  60 var night = "long";
  61
  62 /* what a great and wonderful day */
  63 var day = "great"
  64 ```
  65
  66 Examples of **correct** code for this rule with the `{ "afterBlockComment": true }` option:
  67
  68 ```js
  69 /*eslint lines-around-comment: ["error", { "afterBlockComment": true }]*/
  70
  71 var night = "long";
  72
  73 /* what a great and wonderful day */
  74
  75 var day = "great"
  76 ```
  77
  78 ### beforeLineComment
  79
  80 Examples of **incorrect** code for this rule with the `{ "beforeLineComment": true }` option:
  81
  82 ```js
  83 /*eslint lines-around-comment: ["error", { "beforeLineComment": true }]*/
  84
  85 var night = "long";
  86 // what a great and wonderful day
  87 var day = "great"
  88 ```
  89
  90 Examples of **correct** code for this rule with the `{ "beforeLineComment": true }` option:
  91
  92 ```js
  93 /*eslint lines-around-comment: ["error", { "beforeLineComment": true }]*/
  94
  95 var night = "long";
  96
  97 // what a great and wonderful day
  98 var day = "great"
  99 ```
 100
 101 ### afterLineComment
 102
 103 Examples of **incorrect** code for this rule with the `{ "afterLineComment": true }` option:
 104
 105 ```js
 106 /*eslint lines-around-comment: ["error", { "afterLineComment": true }]*/
 107
 108 var night = "long";
 109 // what a great and wonderful day
 110 var day = "great"
 111 ```
 112
 113 Examples of **correct** code for this rule with the `{ "afterLineComment": true }` option:
 114
 115 ```js
 116 /*eslint lines-around-comment: ["error", { "afterLineComment": true }]*/
 117
 118 var night = "long";
 119 // what a great and wonderful day
 120
 121 var day = "great"
 122 ```
 123
 124 ### allowBlockStart
 125
 126 Examples of **correct** code for this rule with the `{ "beforeLineComment": true, "allowBlockStart": true }` options:
 127
 128 ```js
 129 /*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowBlockStart": true }]*/
 130
 131 function foo(){
 132     // what a great and wonderful day
 133     var day = "great"
 134     return day;
 135 }
 136
 137 if (bar) {
 138     // what a great and wonderful day
 139     foo();
 140 }
 141
 142 class C {
 143     // what a great and wonderful day
 144
 145     method() {
 146         // what a great and wonderful day
 147         foo();
 148     }
 149
 150     static {
 151         // what a great and wonderful day
 152         foo();
 153     }
 154 }
 155 ```
 156
 157 Examples of **correct** code for this rule with the `{ "beforeBlockComment": true, "allowBlockStart": true }` options:
 158
 159 ```js
 160 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowBlockStart": true }]*/
 161
 162 function foo(){
 163     /* what a great and wonderful day */
 164     var day = "great"
 165     return day;
 166 }
 167
 168 if (bar) {
 169     /* what a great and wonderful day */
 170     foo();
 171 }
 172
 173 class C {
 174     /* what a great and wonderful day */
 175
 176     method() {
 177         /* what a great and wonderful day */
 178         foo();
 179     }
 180
 181     static {
 182         /* what a great and wonderful day */
 183         foo();
 184     }
 185 }
 186 ```
 187
 188 ### allowBlockEnd
 189
 190 Examples of **correct** code for this rule with the `{ "afterLineComment": true, "allowBlockEnd": true }` option:
 191
 192 ```js
 193 /*eslint lines-around-comment: ["error", { "afterLineComment": true, "allowBlockEnd": true }]*/
 194
 195 function foo(){
 196     var day = "great"
 197     return day;
 198     // what a great and wonderful day
 199 }
 200
 201 if (bar) {
 202     foo();
 203     // what a great and wonderful day
 204 }
 205
 206 class C {
 207
 208     method() {
 209         foo();
 210         // what a great and wonderful day
 211     }
 212
 213     static {
 214         foo();
 215         // what a great and wonderful day
 216     }
 217
 218     // what a great and wonderful day
 219 }
 220 ```
 221
 222 Examples of **correct** code for this rule with the `{ "afterBlockComment": true, "allowBlockEnd": true }` option:
 223
 224 ```js
 225 /*eslint lines-around-comment: ["error", { "afterBlockComment": true, "allowBlockEnd": true }]*/
 226
 227 function foo(){
 228     var day = "great"
 229     return day;
 230
 231     /* what a great and wonderful day */
 232 }
 233
 234 if (bar) {
 235     foo();
 236
 237     /* what a great and wonderful day */
 238 }
 239
 240 class C {
 241
 242     method() {
 243         foo();
 244
 245         /* what a great and wonderful day */
 246     }
 247
 248     static {
 249         foo();
 250
 251         /* what a great and wonderful day */
 252     }
 253
 254     /* what a great and wonderful day */
 255 }
 256 ```
 257
 258 ### allowClassStart
 259
 260 Examples of **incorrect** code for this rule with the `{ "beforeLineComment": true, "allowClassStart": false }` option:
 261
 262 ```js
 263 /*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowClassStart": false }]*/
 264
 265 class foo {
 266     // what a great and wonderful day
 267     day() {}
 268 };
 269 ```
 270
 271 Examples of **correct** code for this rule with the `{ "beforeLineComment": true, "allowClassStart": false }` option:
 272
 273 ```js
 274 /*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowClassStart": false }]*/
 275
 276 class foo {
 277
 278     // what a great and wonderful day
 279     day() {}
 280 };
 281 ```
 282
 283 Examples of **correct** code for this rule with the `{ "beforeLineComment": true, "allowClassStart": true }` option:
 284
 285 ```js
 286 /*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowClassStart": true }]*/
 287
 288 class foo {
 289     // what a great and wonderful day
 290     day() {}
 291 };
 292 ```
 293
 294 Examples of **incorrect** code for this rule with the `{ "beforeBlockComment": true, "allowClassStart": false }` option:
 295
 296 ```js
 297 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowClassStart": false }]*/
 298
 299 class foo {
 300     /* what a great and wonderful day */
 301     day() {}
 302 };
 303 ```
 304
 305 Examples of **correct** code for this rule with the `{ "beforeBlockComment": true, "allowClassStart": false }` option:
 306
 307 ```js
 308 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowClassStart": false }]*/
 309
 310 class foo {
 311
 312     /* what a great and wonderful day */
 313     day() {}
 314 };
 315 ```
 316
 317 Examples of **correct** code for this rule with the `{ "beforeBlockComment": true, "allowClassStart": true }` option:
 318
 319 ```js
 320 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowClassStart": true }]*/
 321
 322 class foo {
 323     /* what a great and wonderful day */
 324     day() {}
 325 };
 326 ```
 327
 328 ### allowClassEnd
 329
 330 Examples of **correct** code for this rule with the `{ "afterLineComment": true, "allowClassEnd": true }` option:
 331
 332 ```js
 333 /*eslint lines-around-comment: ["error", { "afterLineComment": true, "allowClassEnd": true }]*/
 334
 335 class foo {
 336     day() {}
 337     // what a great and wonderful day
 338 };
 339 ```
 340
 341 Examples of **correct** code for this rule with the `{ "afterBlockComment": true, "allowClassEnd": true }` option:
 342
 343 ```js
 344 /*eslint lines-around-comment: ["error", { "afterBlockComment": true, "allowClassEnd": true }]*/
 345
 346 class foo {
 347     day() {}
 348
 349     /* what a great and wonderful day */
 350 };
 351 ```
 352
 353 ### allowObjectStart
 354
 355 Examples of **correct** code for this rule with the `{ "beforeLineComment": true, "allowObjectStart": true }` option:
 356
 357 ```js
 358 /*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowObjectStart": true }]*/
 359
 360 var foo = {
 361     // what a great and wonderful day
 362     day: "great"
 363 };
 364
 365 const {
 366     // what a great and wonderful day
 367     foo: someDay
 368 } = {foo: "great"};
 369
 370 const {
 371     // what a great and wonderful day
 372     day
 373 } = {day: "great"};
 374 ```
 375
 376 Examples of **correct** code for this rule with the `{ "beforeBlockComment": true, "allowObjectStart": true }` option:
 377
 378 ```js
 379 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowObjectStart": true }]*/
 380
 381 var foo = {
 382     /* what a great and wonderful day */
 383     day: "great"
 384 };
 385
 386 const {
 387     /* what a great and wonderful day */
 388     foo: someDay
 389 } = {foo: "great"};
 390
 391 const {
 392     /* what a great and wonderful day */
 393     day
 394 } = {day: "great"};
 395 ```
 396
 397 ### allowObjectEnd
 398
 399 Examples of **correct** code for this rule with the `{ "afterLineComment": true, "allowObjectEnd": true }` option:
 400
 401 ```js
 402 /*eslint lines-around-comment: ["error", { "afterLineComment": true, "allowObjectEnd": true }]*/
 403
 404 var foo = {
 405     day: "great"
 406     // what a great and wonderful day
 407 };
 408
 409 const {
 410     foo: someDay
 411     // what a great and wonderful day
 412 } = {foo: "great"};
 413
 414 const {
 415     day
 416     // what a great and wonderful day
 417 } = {day: "great"};
 418 ```
 419
 420 Examples of **correct** code for this rule with the `{ "afterBlockComment": true, "allowObjectEnd": true }` option:
 421
 422 ```js
 423 /*eslint lines-around-comment: ["error", { "afterBlockComment": true, "allowObjectEnd": true }]*/
 424
 425 var foo = {
 426     day: "great"
 427
 428     /* what a great and wonderful day */
 429 };
 430
 431 const {
 432     foo: someDay
 433
 434     /* what a great and wonderful day */
 435 } = {foo: "great"};
 436
 437 const {
 438     day
 439
 440     /* what a great and wonderful day */
 441 } = {day: "great"};
 442 ```
 443
 444 ### allowArrayStart
 445
 446 Examples of **correct** code for this rule with the `{ "beforeLineComment": true, "allowArrayStart": true }` option:
 447
 448 ```js
 449 /*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowArrayStart": true }]*/
 450
 451 var day = [
 452     // what a great and wonderful day
 453     "great",
 454     "wonderful"
 455 ];
 456
 457 const [
 458     // what a great and wonderful day
 459     someDay
 460 ] = ["great", "not great"];
 461 ```
 462
 463 Examples of **correct** code for this rule with the `{ "beforeBlockComment": true, "allowArrayStart": true }` option:
 464
 465 ```js
 466 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowArrayStart": true }]*/
 467
 468 var day = [
 469     /* what a great and wonderful day */
 470     "great",
 471     "wonderful"
 472 ];
 473
 474 const [
 475     /* what a great and wonderful day */
 476     someDay
 477 ] = ["great", "not great"];
 478 ```
 479
 480 ### allowArrayEnd
 481
 482 Examples of **correct** code for this rule with the `{ "afterLineComment": true, "allowArrayEnd": true }` option:
 483
 484 ```js
 485 /*eslint lines-around-comment: ["error", { "afterLineComment": true, "allowArrayEnd": true }]*/
 486
 487 var day = [
 488     "great",
 489     "wonderful"
 490     // what a great and wonderful day
 491 ];
 492
 493 const [
 494     someDay
 495     // what a great and wonderful day
 496 ] = ["great", "not great"];
 497 ```
 498
 499 Examples of **correct** code for this rule with the `{ "afterBlockComment": true, "allowArrayEnd": true }` option:
 500
 501 ```js
 502 /*eslint lines-around-comment: ["error", { "afterBlockComment": true, "allowArrayEnd": true }]*/
 503
 504 var day = [
 505     "great",
 506     "wonderful"
 507
 508     /* what a great and wonderful day */
 509 ];
 510
 511 const [
 512     someDay
 513
 514     /* what a great and wonderful day */
 515 ] = ["great", "not great"];
 516 ```
 517
 518
 519 ### ignorePattern
 520
 521 By default this rule ignores comments starting with the following words: `eslint`, `jshint`, `jslint`, `istanbul`, `global`, `exported`, `jscs`. To ignore more comments in addition to the defaults, set the `ignorePattern` option to a string pattern that will be passed to the [`RegExp` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp).
 522
 523 Examples of **correct** code for the `ignorePattern` option:
 524
 525 ```js
 526 /*eslint lines-around-comment: ["error"]*/
 527
 528 foo();
 529 /* eslint mentioned in this comment */,
 530 bar();
 531
 532
 533 /*eslint lines-around-comment: ["error", { "ignorePattern": "pragma" }] */
 534
 535 foo();
 536 /* a valid comment using pragma in it */
 537 ```
 538
 539 Examples of **incorrect** code for the `ignorePattern` option:
 540
 541 ```js
 542 /*eslint lines-around-comment: ["error", { "ignorePattern": "pragma" }] */
 543
 544 1 + 1;
 545 /* something else */
 546 ```
 547
 548 ### applyDefaultIgnorePatterns
 549
 550 Default ignore patterns are applied even when `ignorePattern` is provided. If you want to omit default patterns, set this option to `false`.
 551
 552 Examples of **correct** code for the `{ "applyDefaultIgnorePatterns": false }` option:
 553
 554 ```js
 555 /*eslint lines-around-comment: ["error", { "ignorePattern": "pragma", applyDefaultIgnorePatterns: false }] */
 556
 557 foo();
 558 /* a valid comment using pragma in it */
 559 ```
 560
 561 Examples of **incorrect** code for the `{ "applyDefaultIgnorePatterns": false }` option:
 562
 563 ```js
 564 /*eslint lines-around-comment: ["error", { "applyDefaultIgnorePatterns": false }] */
 565
 566 foo();
 567 /* eslint mentioned in comment */
 568
 569 ```
 570
 571
 572 ## When Not To Use It
 573
 574 Many people enjoy a terser code style and don't mind comments bumping up against code. If you fall into that category this rule is not for you.
 575
 576 ## Related Rules
 577
 578 * [space-before-blocks](space-before-blocks.md)
 579 * [spaced-comment](spaced-comment.md)