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
  19 * `"allowBlockEnd": true` allows comments to appear at the end of block statements
  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
 138 Examples of **correct** code for this rule with the `{ "beforeBlockComment": true, "allowBlockStart": true }` options:
 139
 140 ```js
 141 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowBlockStart": true }]*/
 142
 143 function foo(){
 144     /* what a great and wonderful day */
 145     var day = "great"
 146     return day;
 147 }
 148 ```
 149
 150 ### allowBlockEnd
 151
 152 Examples of **correct** code for this rule with the `{ "afterLineComment": true, "allowBlockEnd": true }` option:
 153
 154 ```js
 155 /*eslint lines-around-comment: ["error", { "afterLineComment": true, "allowBlockEnd": true }]*/
 156
 157 function foo(){
 158     var day = "great"
 159     return day;
 160     // what a great and wonderful day
 161 }
 162 ```
 163
 164 Examples of **correct** code for this rule with the `{ "afterBlockComment": true, "allowBlockEnd": true }` option:
 165
 166 ```js
 167 /*eslint lines-around-comment: ["error", { "afterBlockComment": true, "allowBlockEnd": true }]*/
 168
 169 function foo(){
 170     var day = "great"
 171     return day;
 172
 173     /* what a great and wonderful day */
 174 }
 175 ```
 176
 177 ### allowClassStart
 178
 179 Examples of **incorrect** code for this rule with the `{ "beforeLineComment": true, "allowClassStart": false }` option:
 180
 181 ```js
 182 /*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowClassStart": false }]*/
 183
 184 class foo {
 185     // what a great and wonderful day
 186     day() {}
 187 };
 188 ```
 189
 190 Examples of **correct** code for this rule with the `{ "beforeLineComment": true, "allowClassStart": false }` option:
 191
 192 ```js
 193 /*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowClassStart": false }]*/
 194
 195 class foo {
 196
 197     // what a great and wonderful day
 198     day() {}
 199 };
 200 ```
 201
 202 Examples of **correct** code for this rule with the `{ "beforeLineComment": true, "allowClassStart": true }` option:
 203
 204 ```js
 205 /*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowClassStart": true }]*/
 206
 207 class foo {
 208     // what a great and wonderful day
 209     day() {}
 210 };
 211 ```
 212
 213 Examples of **incorrect** code for this rule with the `{ "beforeBlockComment": true, "allowClassStart": false }` option:
 214
 215 ```js
 216 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowClassStart": false }]*/
 217
 218 class foo {
 219     /* what a great and wonderful day */
 220     day() {}
 221 };
 222 ```
 223
 224 Examples of **correct** code for this rule with the `{ "beforeBlockComment": true, "allowClassStart": false }` option:
 225
 226 ```js
 227 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowClassStart": false }]*/
 228
 229 class foo {
 230
 231     /* what a great and wonderful day */
 232     day() {}
 233 };
 234 ```
 235
 236 Examples of **correct** code for this rule with the `{ "beforeBlockComment": true, "allowClassStart": true }` option:
 237
 238 ```js
 239 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowClassStart": true }]*/
 240
 241 class foo {
 242     /* what a great and wonderful day */
 243     day() {}
 244 };
 245 ```
 246
 247 ### allowClassEnd
 248
 249 Examples of **correct** code for this rule with the `{ "afterLineComment": true, "allowClassEnd": true }` option:
 250
 251 ```js
 252 /*eslint lines-around-comment: ["error", { "afterLineComment": true, "allowClassEnd": true }]*/
 253
 254 class foo {
 255     day() {}
 256     // what a great and wonderful day
 257 };
 258 ```
 259
 260 Examples of **correct** code for this rule with the `{ "afterBlockComment": true, "allowClassEnd": true }` option:
 261
 262 ```js
 263 /*eslint lines-around-comment: ["error", { "afterBlockComment": true, "allowClassEnd": true }]*/
 264
 265 class foo {
 266     day() {}
 267
 268     /* what a great and wonderful day */
 269 };
 270 ```
 271
 272 ### allowObjectStart
 273
 274 Examples of **correct** code for this rule with the `{ "beforeLineComment": true, "allowObjectStart": true }` option:
 275
 276 ```js
 277 /*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowObjectStart": true }]*/
 278
 279 var foo = {
 280     // what a great and wonderful day
 281     day: "great"
 282 };
 283
 284 const {
 285     // what a great and wonderful day
 286     foo: someDay
 287 } = {foo: "great"};
 288
 289 const {
 290     // what a great and wonderful day
 291     day
 292 } = {day: "great"};
 293 ```
 294
 295 Examples of **correct** code for this rule with the `{ "beforeBlockComment": true, "allowObjectStart": true }` option:
 296
 297 ```js
 298 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowObjectStart": true }]*/
 299
 300 var foo = {
 301     /* what a great and wonderful day */
 302     day: "great"
 303 };
 304
 305 const {
 306     /* what a great and wonderful day */
 307     foo: someDay
 308 } = {foo: "great"};
 309
 310 const {
 311     /* what a great and wonderful day */
 312     day
 313 } = {day: "great"};
 314 ```
 315
 316 ### allowObjectEnd
 317
 318 Examples of **correct** code for this rule with the `{ "afterLineComment": true, "allowObjectEnd": true }` option:
 319
 320 ```js
 321 /*eslint lines-around-comment: ["error", { "afterLineComment": true, "allowObjectEnd": true }]*/
 322
 323 var foo = {
 324     day: "great"
 325     // what a great and wonderful day
 326 };
 327
 328 const {
 329     foo: someDay
 330     // what a great and wonderful day
 331 } = {foo: "great"};
 332
 333 const {
 334     day
 335     // what a great and wonderful day
 336 } = {day: "great"};
 337 ```
 338
 339 Examples of **correct** code for this rule with the `{ "afterBlockComment": true, "allowObjectEnd": true }` option:
 340
 341 ```js
 342 /*eslint lines-around-comment: ["error", { "afterBlockComment": true, "allowObjectEnd": true }]*/
 343
 344 var foo = {
 345     day: "great"
 346
 347     /* what a great and wonderful day */
 348 };
 349
 350 const {
 351     foo: someDay
 352
 353     /* what a great and wonderful day */
 354 } = {foo: "great"};
 355
 356 const {
 357     day
 358
 359     /* what a great and wonderful day */
 360 } = {day: "great"};
 361 ```
 362
 363 ### allowArrayStart
 364
 365 Examples of **correct** code for this rule with the `{ "beforeLineComment": true, "allowArrayStart": true }` option:
 366
 367 ```js
 368 /*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowArrayStart": true }]*/
 369
 370 var day = [
 371     // what a great and wonderful day
 372     "great",
 373     "wonderful"
 374 ];
 375
 376 const [
 377     // what a great and wonderful day
 378     someDay
 379 ] = ["great", "not great"];
 380 ```
 381
 382 Examples of **correct** code for this rule with the `{ "beforeBlockComment": true, "allowArrayStart": true }` option:
 383
 384 ```js
 385 /*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowArrayStart": true }]*/
 386
 387 var day = [
 388     /* what a great and wonderful day */
 389     "great",
 390     "wonderful"
 391 ];
 392
 393 const [
 394     /* what a great and wonderful day */
 395     someDay
 396 ] = ["great", "not great"];
 397 ```
 398
 399 ### allowArrayEnd
 400
 401 Examples of **correct** code for this rule with the `{ "afterLineComment": true, "allowArrayEnd": true }` option:
 402
 403 ```js
 404 /*eslint lines-around-comment: ["error", { "afterLineComment": true, "allowArrayEnd": true }]*/
 405
 406 var day = [
 407     "great",
 408     "wonderful"
 409     // what a great and wonderful day
 410 ];
 411
 412 const [
 413     someDay
 414     // what a great and wonderful day
 415 ] = ["great", "not great"];
 416 ```
 417
 418 Examples of **correct** code for this rule with the `{ "afterBlockComment": true, "allowArrayEnd": true }` option:
 419
 420 ```js
 421 /*eslint lines-around-comment: ["error", { "afterBlockComment": true, "allowArrayEnd": true }]*/
 422
 423 var day = [
 424     "great",
 425     "wonderful"
 426
 427     /* what a great and wonderful day */
 428 ];
 429
 430 const [
 431     someDay
 432
 433     /* what a great and wonderful day */
 434 ] = ["great", "not great"];
 435 ```
 436
 437
 438 ### ignorePattern
 439
 440 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).
 441
 442 Examples of **correct** code for the `ignorePattern` option:
 443
 444 ```js
 445 /*eslint lines-around-comment: ["error"]*/
 446
 447 foo();
 448 /* eslint mentioned in this comment */,
 449 bar();
 450
 451
 452 /*eslint lines-around-comment: ["error", { "ignorePattern": "pragma" }] */
 453
 454 foo();
 455 /* a valid comment using pragma in it */
 456 ```
 457
 458 Examples of **incorrect** code for the `ignorePattern` option:
 459
 460 ```js
 461 /*eslint lines-around-comment: ["error", { "ignorePattern": "pragma" }] */
 462
 463 1 + 1;
 464 /* something else */
 465 ```
 466
 467 ### applyDefaultIgnorePatterns
 468
 469 Default ignore patterns are applied even when `ignorePattern` is provided. If you want to omit default patterns, set this option to `false`.
 470
 471 Examples of **correct** code for the `{ "applyDefaultIgnorePatterns": false }` option:
 472
 473 ```js
 474 /*eslint lines-around-comment: ["error", { "ignorePattern": "pragma", applyDefaultIgnorePatterns: false }] */
 475
 476 foo();
 477 /* a valid comment using pragma in it */
 478 ```
 479
 480 Examples of **incorrect** code for the `{ "applyDefaultIgnorePatterns": false }` option:
 481
 482 ```js
 483 /*eslint lines-around-comment: ["error", { "applyDefaultIgnorePatterns": false }] */
 484
 485 foo();
 486 /* eslint mentioned in comment */
 487
 488 ```
 489
 490
 491 ## When Not To Use It
 492
 493 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.
 494
 495 ## Related Rules
 496
 497 * [space-before-blocks](space-before-blocks.md)
 498 * [spaced-comment](spaced-comment.md)