eslint/docs/src/rules/comma-style.md

   1 ---
   2 title: comma-style
   3 layout: doc
   4 rule_type: layout
   5 related_rules:
   6 - operator-linebreak
   7 further_reading:
   8 - https://gist.github.com/isaacs/357981
   9 ---
  10
  11
  12
  13 The Comma Style rule enforces styles for comma-separated lists. There are two comma styles primarily used in JavaScript:
  14
  15 * The standard style, in which commas are placed at the end of the current line
  16 * Comma First style, in which commas are placed at the start of the next line
  17
  18 One of the justifications for using Comma First style is that it can help track missing and trailing commas. These are problematic because missing commas in variable declarations can lead to the leakage of global variables and trailing commas can lead to errors in older versions of IE.
  19
  20 ## Rule Details
  21
  22 This rule enforce consistent comma style in array literals, object literals, and variable declarations.
  23
  24 This rule does not apply in either of the following cases:
  25
  26 * comma preceded and followed by linebreak (lone comma)
  27 * single-line array literals, object literals, and variable declarations
  28
  29 ## Options
  30
  31 This rule has a string option:
  32
  33 * `"last"` (default) requires a comma after and on the same line as an array element, object property, or variable declaration
  34 * `"first"` requires a comma before and on the same line as an array element, object property, or variable declaration
  35
  36 This rule also accepts an additional `exceptions` object:
  37
  38 * `"exceptions"` has properties whose names correspond to node types in the abstract syntax tree (AST) of JavaScript code:
  39
  40     * `"ArrayExpression": true` ignores comma style in array literals
  41     * `"ArrayPattern": true` ignores comma style in array patterns of destructuring
  42     * `"ArrowFunctionExpression": true` ignores comma style in the parameters of arrow function expressions
  43     * `"CallExpression": true` ignores comma style in the arguments of function calls
  44     * `"FunctionDeclaration": true` ignores comma style in the parameters of function declarations
  45     * `"FunctionExpression": true` ignores comma style in the parameters of function expressions
  46     * `"ImportDeclaration": true` ignores comma style in the specifiers of import declarations
  47     * `"ObjectExpression": true` ignores comma style in object literals
  48     * `"ObjectPattern": true` ignores comma style in object patterns of destructuring
  49     * `"VariableDeclaration": true` ignores comma style in variable declarations
  50     * `"NewExpression": true` ignores comma style in the parameters of constructor expressions
  51
  52 A way to determine the node types as defined by [ESTree](https://github.com/estree/estree) is to use [AST Explorer](https://astexplorer.net/) with the espree parser.
  53
  54 ### last
  55
  56 Examples of **incorrect** code for this rule with the default `"last"` option:
  57
  58 :::incorrect
  59
  60 ```js
  61 /*eslint comma-style: ["error", "last"]*/
  62
  63 var foo = 1
  64 ,
  65 bar = 2;
  66
  67 var foo = 1
  68   , bar = 2;
  69
  70 var foo = ["apples"
  71            , "oranges"];
  72
  73 function bar() {
  74     return {
  75         "a": 1
  76         ,"b:": 2
  77     };
  78 }
  79 ```
  80
  81 :::
  82
  83 Examples of **correct** code for this rule with the default `"last"` option:
  84
  85 :::correct
  86
  87 ```js
  88 /*eslint comma-style: ["error", "last"]*/
  89
  90 var foo = 1, bar = 2;
  91
  92 var foo = 1,
  93     bar = 2;
  94
  95 var foo = ["apples",
  96            "oranges"];
  97
  98 function bar() {
  99     return {
 100         "a": 1,
 101         "b:": 2
 102     };
 103 }
 104 ```
 105
 106 :::
 107
 108 ### first
 109
 110 Examples of **incorrect** code for this rule with the `"first"` option:
 111
 112 :::incorrect
 113
 114 ```js
 115 /*eslint comma-style: ["error", "first"]*/
 116
 117 var foo = 1,
 118     bar = 2;
 119
 120 var foo = ["apples",
 121            "oranges"];
 122
 123 function bar() {
 124     return {
 125         "a": 1,
 126         "b:": 2
 127     };
 128 }
 129 ```
 130
 131 :::
 132
 133 Examples of **correct** code for this rule with the `"first"` option:
 134
 135 :::correct
 136
 137 ```js
 138 /*eslint comma-style: ["error", "first"]*/
 139
 140 var foo = 1, bar = 2;
 141
 142 var foo = 1
 143     ,bar = 2;
 144
 145 var foo = ["apples"
 146           ,"oranges"];
 147
 148 function bar() {
 149     return {
 150         "a": 1
 151         ,"b:": 2
 152     };
 153 }
 154 ```
 155
 156 :::
 157
 158 ### exceptions
 159
 160 An example use case is to enforce comma style *only* in var statements.
 161
 162 Examples of **incorrect** code for this rule with sample `"first", { "exceptions": { … } }` options:
 163
 164 :::incorrect
 165
 166 ```js
 167 /*eslint comma-style: ["error", "first", { "exceptions": { "ArrayExpression": true, "ObjectExpression": true } }]*/
 168
 169 var o = {},
 170     a = [];
 171 ```
 172
 173 :::
 174
 175 Examples of **correct** code for this rule with sample `"first", { "exceptions": { … } }` options:
 176
 177 :::correct
 178
 179 ```js
 180 /*eslint comma-style: ["error", "first", { "exceptions": { "ArrayExpression": true, "ObjectExpression": true } }]*/
 181
 182 var o = {fst:1,
 183          snd: [1,
 184                2]}
 185   , a = [];
 186 ```
 187
 188 :::
 189
 190 ## When Not To Use It
 191
 192 This rule can safely be turned off if your project does not care about enforcing a consistent comma style.