eslint/docs/rules/comma-style.md

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