eslint/docs/rules/padding-line-between-statements.md

   1 # Require or disallow padding lines between statements (padding-line-between-statements)
   2
   3 This rule requires or disallows blank lines between the given 2 kinds of statements.
   4 Properly blank lines help developers to understand the code.
   5
   6 For example, the following configuration requires a blank line between a variable declaration and a `return` statement.
   7
   8 ```js
   9 /*eslint padding-line-between-statements: [
  10     "error",
  11     { blankLine: "always", prev: "var", next: "return" }
  12 ]*/
  13
  14 function foo() {
  15     var a = 1;
  16
  17     return a;
  18 }
  19 ```
  20
  21 ## Rule Details
  22
  23 This rule does nothing if no configurations are provided.
  24
  25 A configuration is an object which has 3 properties; `blankLine`, `prev` and `next`. For example, `{ blankLine: "always", prev: "var", next: "return" }` means "one or more blank lines are required between a variable declaration and a `return` statement."
  26 You can supply any number of configurations. If a statement pair matches multiple configurations, the last matched configuration will be used.
  27
  28 ```json
  29 {
  30     "padding-line-between-statements": [
  31         "error",
  32         { "blankLine": LINEBREAK_TYPE, "prev": STATEMENT_TYPE, "next": STATEMENT_TYPE },
  33         { "blankLine": LINEBREAK_TYPE, "prev": STATEMENT_TYPE, "next": STATEMENT_TYPE },
  34         { "blankLine": LINEBREAK_TYPE, "prev": STATEMENT_TYPE, "next": STATEMENT_TYPE },
  35         { "blankLine": LINEBREAK_TYPE, "prev": STATEMENT_TYPE, "next": STATEMENT_TYPE },
  36         ...
  37     ]
  38 }
  39 ```
  40
  41 - `LINEBREAK_TYPE` is one of the following.
  42     - `"any"` just ignores the statement pair.
  43     - `"never"` disallows blank lines.
  44     - `"always"` requires one or more blank lines. Note it does not count lines that comments exist as blank lines.
  45
  46 - `STATEMENT_TYPE` is one of the following, or an array of the following.
  47     - `"*"` is wildcard. This matches any statements.
  48     - `"block"` is lonely blocks.
  49     - `"block-like"` is block like statements. This matches statements that the last token is the closing brace of blocks; e.g. `{ }`, `if (a) { }`, and `while (a) { }`. Also matches immediately invoked function expression statements.
  50     - `"break"` is `break` statements.
  51     - `"case"` is `case` clauses in `switch` statements.
  52     - `"cjs-export"` is `export` statements of CommonJS; e.g. `module.exports = 0`, `module.exports.foo = 1`, and `exports.foo = 2`. This is a special case of assignment.
  53     - `"cjs-import"` is `import` statements of CommonJS; e.g. `const foo = require("foo")`. This is a special case of variable declarations.
  54     - `"class"` is `class` declarations.
  55     - `"const"` is `const` variable declarations, both single-line and multiline.
  56     - `"continue"` is `continue` statements.
  57     - `"debugger"` is `debugger` statements.
  58     - `"default"` is `default` clauses in `switch` statements.
  59     - `"directive"` is directive prologues. This matches directives; e.g. `"use strict"`.
  60     - `"do"` is `do-while` statements. This matches all statements that the first token is `do` keyword.
  61     - `"empty"` is empty statements.
  62     - `"export"` is `export` declarations.
  63     - `"expression"` is expression statements.
  64     - `"for"` is `for` loop families. This matches all statements that the first token is `for` keyword.
  65     - `"function"` is function declarations.
  66     - `"if"` is `if` statements.
  67     - `"iife"` is immediately invoked function expression statements. This matches calls on a function expression, optionally prefixed with a unary operator.
  68     - `"import"` is `import` declarations.
  69     - `"let"` is `let` variable declarations, both single-line and multiline.
  70     - `"multiline-block-like"` is block like statements. This is the same as `block-like` type, but only if the block is multiline.
  71     - `"multiline-const"` is multiline `const` variable declarations.
  72     - `"multiline-expression"` is expression statements. This is the same as `expression` type, but only if the statement is multiline.
  73     - `"multiline-let"` is multiline `let` variable declarations.
  74     - `"multiline-var"` is multiline `var` variable declarations.
  75     - `"return"` is `return` statements.
  76     - `"singleline-const"` is single-line `const` variable declarations.
  77     - `"singleline-let"` is single-line `let` variable declarations.
  78     - `"singleline-var"` is single-line `var` variable declarations.
  79     - `"switch"` is `switch` statements.
  80     - `"throw"` is `throw` statements.
  81     - `"try"` is `try` statements.
  82     - `"var"` is `var` variable declarations, both single-line and multiline.
  83     - `"while"` is `while` loop statements.
  84     - `"with"` is `with` statements.
  85
  86 ## Examples
  87
  88 This configuration would require blank lines before all `return` statements, like the [newline-before-return] rule.
  89
  90 Examples of **incorrect** code for the `[{ blankLine: "always", prev: "*", next: "return" }]` configuration:
  91
  92 ```js
  93 /*eslint padding-line-between-statements: [
  94     "error",
  95     { blankLine: "always", prev: "*", next: "return" }
  96 ]*/
  97
  98 function foo() {
  99     bar();
 100     return;
 101 }
 102 ```
 103
 104 Examples of **correct** code for the `[{ blankLine: "always", prev: "*", next: "return" }]` configuration:
 105
 106 ```js
 107 /*eslint padding-line-between-statements: [
 108     "error",
 109     { blankLine: "always", prev: "*", next: "return" }
 110 ]*/
 111
 112 function foo() {
 113     bar();
 114
 115     return;
 116 }
 117
 118 function foo() {
 119     return;
 120 }
 121 ```
 122
 123 ----
 124
 125 This configuration would require blank lines after every sequence of variable declarations, like the [newline-after-var] rule.
 126
 127 Examples of **incorrect** code for the `[{ blankLine: "always", prev: ["const", "let", "var"], next: "*"}, { blankLine: "any", prev: ["const", "let", "var"], next: ["const", "let", "var"]}]` configuration:
 128
 129 ```js
 130 /*eslint padding-line-between-statements: [
 131     "error",
 132     { blankLine: "always", prev: ["const", "let", "var"], next: "*"},
 133     { blankLine: "any",    prev: ["const", "let", "var"], next: ["const", "let", "var"]}
 134 ]*/
 135
 136 function foo() {
 137     var a = 0;
 138     bar();
 139 }
 140
 141 function foo() {
 142     let a = 0;
 143     bar();
 144 }
 145
 146 function foo() {
 147     const a = 0;
 148     bar();
 149 }
 150
 151 class C {
 152     static {
 153         let a = 0;
 154         bar();
 155     }
 156 }
 157 ```
 158
 159 Examples of **correct** code for the `[{ blankLine: "always", prev: ["const", "let", "var"], next: "*"}, { blankLine: "any", prev: ["const", "let", "var"], next: ["const", "let", "var"]}]` configuration:
 160
 161 ```js
 162 /*eslint padding-line-between-statements: [
 163     "error",
 164     { blankLine: "always", prev: ["const", "let", "var"], next: "*"},
 165     { blankLine: "any",    prev: ["const", "let", "var"], next: ["const", "let", "var"]}
 166 ]*/
 167
 168 function foo() {
 169     var a = 0;
 170     var b = 0;
 171
 172     bar();
 173 }
 174
 175 function foo() {
 176     let a = 0;
 177     const b = 0;
 178
 179     bar();
 180 }
 181
 182 function foo() {
 183     const a = 0;
 184     const b = 0;
 185
 186     bar();
 187 }
 188
 189 class C {
 190     static {
 191         let a = 0;
 192         let b = 0;
 193
 194         bar();
 195     }
 196 }
 197 ```
 198
 199 ----
 200
 201 This configuration would require blank lines after all directive prologues, like the [lines-around-directive] rule.
 202
 203 Examples of **incorrect** code for the `[{ blankLine: "always", prev: "directive", next: "*" }, { blankLine: "any", prev: "directive", next: "directive" }]` configuration:
 204
 205 ```js
 206 /*eslint padding-line-between-statements: [
 207     "error",
 208     { blankLine: "always", prev: "directive", next: "*" },
 209     { blankLine: "any",    prev: "directive", next: "directive" }
 210 ]*/
 211
 212 "use strict";
 213 foo();
 214 ```
 215
 216 Examples of **correct** code for the `[{ blankLine: "always", prev: "directive", next: "*" }, { blankLine: "any", prev: "directive", next: "directive" }]` configuration:
 217
 218 ```js
 219 /*eslint padding-line-between-statements: [
 220     "error",
 221     { blankLine: "always", prev: "directive", next: "*" },
 222     { blankLine: "any",    prev: "directive", next: "directive" }
 223 ]*/
 224
 225 "use strict";
 226 "use asm";
 227
 228 foo();
 229 ```
 230
 231 ----
 232
 233 This configuration would require blank lines between clauses in `switch` statements.
 234
 235 Examples of **incorrect** code for the `[{ blankLine: "always", prev: ["case", "default"], next: "*" }]` configuration:
 236
 237 ```js
 238 /*eslint padding-line-between-statements: [
 239     "error",
 240     { blankLine: "always", prev: ["case", "default"], next: "*" }
 241 ]*/
 242
 243 switch (foo) {
 244     case 1:
 245         bar();
 246         break;
 247     case 2:
 248     case 3:
 249         baz();
 250         break;
 251     default:
 252         quux();
 253 }
 254 ```
 255
 256 Examples of **correct** code for the `[{ blankLine: "always", prev: ["case", "default"], next: "*" }]` configuration:
 257
 258 ```js
 259 /*eslint padding-line-between-statements: [
 260     "error",
 261     { blankLine: "always", prev: ["case", "default"], next: "*" }
 262 ]*/
 263
 264 switch (foo) {
 265     case 1:
 266         bar();
 267         break;
 268
 269     case 2:
 270
 271     case 3:
 272         baz();
 273         break;
 274
 275     default:
 276         quux();
 277 }
 278 ```
 279
 280 ## Compatibility
 281
 282 - **JSCS:** [requirePaddingNewLineAfterVariableDeclaration]
 283 - **JSCS:** [requirePaddingNewLinesAfterBlocks]
 284 - **JSCS:** [disallowPaddingNewLinesAfterBlocks]
 285 - **JSCS:** [requirePaddingNewLinesAfterUseStrict]
 286 - **JSCS:** [disallowPaddingNewLinesAfterUseStrict]
 287 - **JSCS:** [requirePaddingNewLinesBeforeExport]
 288 - **JSCS:** [disallowPaddingNewLinesBeforeExport]
 289 - **JSCS:** [requirePaddingNewlinesBeforeKeywords]
 290 - **JSCS:** [disallowPaddingNewlinesBeforeKeywords]
 291
 292 ## When Not To Use It
 293
 294 If you don't want to notify warnings about linebreaks, then it's safe to disable this rule.
 295
 296 [lines-around-directive]: https://eslint.org/docs/rules/lines-around-directive
 297 [newline-after-var]: https://eslint.org/docs/rules/newline-after-var
 298 [newline-before-return]: https://eslint.org/docs/rules/newline-before-return
 299 [requirePaddingNewLineAfterVariableDeclaration]: https://jscs-dev.github.io/rule/requirePaddingNewLineAfterVariableDeclaration
 300 [requirePaddingNewLinesAfterBlocks]: https://jscs-dev.github.io/rule/requirePaddingNewLinesAfterBlocks
 301 [disallowPaddingNewLinesAfterBlocks]: https://jscs-dev.github.io/rule/disallowPaddingNewLinesAfterBlocks
 302 [requirePaddingNewLinesAfterUseStrict]: https://jscs-dev.github.io/rule/requirePaddingNewLinesAfterUseStrict
 303 [disallowPaddingNewLinesAfterUseStrict]: https://jscs-dev.github.io/rule/disallowPaddingNewLinesAfterUseStrict
 304 [requirePaddingNewLinesBeforeExport]: https://jscs-dev.github.io/rule/requirePaddingNewLinesBeforeExport
 305 [disallowPaddingNewLinesBeforeExport]: https://jscs-dev.github.io/rule/disallowPaddingNewLinesBeforeExport
 306 [requirePaddingNewlinesBeforeKeywords]: https://jscs-dev.github.io/rule/requirePaddingNewlinesBeforeKeywords
 307 [disallowPaddingNewlinesBeforeKeywords]: https://jscs-dev.github.io/rule/disallowPaddingNewlinesBeforeKeywords