eslint/docs/src/rules/spaced-comment.md

   1 ---
   2 title: spaced-comment
   3 layout: doc
   4 rule_type: suggestion
   5 related_rules:
   6 - spaced-line-comment
   7 ---
   8
   9
  10
  11 Some style guides require or disallow a whitespace immediately after the initial `//` or `/*` of a comment.
  12 Whitespace after the `//` or `/*` makes it easier to read text in comments.
  13 On the other hand, commenting out code is easier without having to put a whitespace right after the `//` or `/*`.
  14
  15 ## Rule Details
  16
  17 This rule will enforce consistency of spacing after the start of a comment `//` or `/*`. It also provides several
  18 exceptions for various documentation styles.
  19
  20 ## Options
  21
  22 The rule takes two options.
  23
  24 * The first is a string which be either `"always"` or `"never"`. The default is `"always"`.
  25
  26     * If `"always"` then the `//` or `/*` must be followed by at least one whitespace.
  27
  28     * If `"never"` then there should be no whitespace following.
  29
  30 * This rule can also take a 2nd option, an object with any of the following keys: `"exceptions"` and `"markers"`.
  31
  32     * The `"exceptions"` value is an array of string patterns which are considered exceptions to the rule. The rule will not warn when the pattern starts from the beginning of the comment and repeats until the end of the line or `*/` if the comment is a single line comment.
  33     Please note that exceptions are ignored if the first argument is `"never"`.
  34
  35     ```js
  36     "spaced-comment": ["error", "always", { "exceptions": ["-", "+"] }]
  37     ```
  38
  39     * The `"markers"` value is an array of string patterns which are considered markers for docblock-style comments,
  40     such as an additional `/`, used to denote documentation read by doxygen, vsdoc, etc. which must have additional characters.
  41     The `"markers"` array will apply regardless of the value of the first argument, e.g. `"always"` or `"never"`.
  42
  43     ```js
  44     "spaced-comment": ["error", "always", { "markers": ["/"] }]
  45     ```
  46
  47 The difference between a marker and an exception is that a marker only appears at the beginning of the comment whereas
  48 exceptions can occur anywhere in the comment string.
  49
  50 You can also define separate exceptions and markers for block and line comments. The `"block"` object can have an additional key `"balanced"`, a boolean that specifies if inline block comments should have balanced spacing. The default value is `false`.
  51
  52 * If `"balanced": true` and `"always"` then the `/*` must be followed by at least one whitespace, and the `*/` must be preceded by at least one whitespace.
  53
  54 * If `"balanced": true` and `"never"` then there should be no whitespace following `/*` or preceding `*/`.
  55
  56 * If `"balanced": false` then balanced whitespace is not enforced.
  57
  58 ```json
  59 "spaced-comment": ["error", "always", {
  60     "line": {
  61         "markers": ["/"],
  62         "exceptions": ["-", "+"]
  63     },
  64     "block": {
  65         "markers": ["!"],
  66         "exceptions": ["*"],
  67         "balanced": true
  68     }
  69 }]
  70 ```
  71
  72 ### always
  73
  74 Examples of **incorrect** code for this rule with the `"always"` option:
  75
  76 ::: incorrect
  77
  78 ```js
  79 /*eslint spaced-comment: ["error", "always"]*/
  80
  81 //This is a comment with no whitespace at the beginning
  82
  83 /*This is a comment with no whitespace at the beginning */
  84 ```
  85
  86 :::
  87
  88 ::: incorrect
  89
  90 ```js
  91 /* eslint spaced-comment: ["error", "always", { "block": { "balanced": true } }] */
  92 /* This is a comment with whitespace at the beginning but not the end*/
  93 ```
  94
  95 :::
  96
  97 Examples of **correct** code for this rule with the `"always"` option:
  98
  99 ::: correct
 100
 101 ```js
 102 /* eslint spaced-comment: ["error", "always"] */
 103
 104 // This is a comment with a whitespace at the beginning
 105
 106 /* This is a comment with a whitespace at the beginning */
 107
 108 /*
 109  * This is a comment with a whitespace at the beginning
 110  */
 111
 112 /*
 113 This comment has a newline
 114 */
 115 ```
 116
 117 :::
 118
 119 ::: correct
 120
 121 ```js
 122 /* eslint spaced-comment: ["error", "always"] */
 123
 124 /**
 125 * I am jsdoc
 126 */
 127 ```
 128
 129 :::
 130
 131 ### never
 132
 133 Examples of **incorrect** code for this rule with the `"never"` option:
 134
 135 ::: incorrect
 136
 137 ```js
 138 /*eslint spaced-comment: ["error", "never"]*/
 139
 140 // This is a comment with a whitespace at the beginning
 141
 142 /* This is a comment with a whitespace at the beginning */
 143
 144 /* \nThis is a comment with a whitespace at the beginning */
 145 ```
 146
 147 :::
 148
 149 ::: incorrect
 150
 151 ```js
 152 /*eslint spaced-comment: ["error", "never", { "block": { "balanced": true } }]*/
 153 /*This is a comment with whitespace at the end */
 154 ```
 155
 156 :::
 157
 158 Examples of **correct** code for this rule with the `"never"` option:
 159
 160 ::: correct
 161
 162 ```js
 163 /*eslint spaced-comment: ["error", "never"]*/
 164
 165 /*This is a comment with no whitespace at the beginning */
 166 ```
 167
 168 :::
 169
 170 ::: correct
 171
 172 ```js
 173 /*eslint spaced-comment: ["error", "never"]*/
 174
 175 /**
 176 * I am jsdoc
 177 */
 178 ```
 179
 180 :::
 181
 182 ### exceptions
 183
 184 Examples of **incorrect** code for this rule with the `"always"` option combined with `"exceptions"`:
 185
 186 ::: incorrect
 187
 188 ```js
 189 /* eslint spaced-comment: ["error", "always", { "block": { "exceptions": ["-"] } }] */
 190
 191 //--------------
 192 // Comment block
 193 //--------------
 194 ```
 195
 196 :::
 197
 198 ::: incorrect
 199
 200 ```js
 201 /* eslint spaced-comment: ["error", "always", { "exceptions": ["-", "+"] }] */
 202
 203 //------++++++++
 204 // Comment block
 205 //------++++++++
 206 ```
 207
 208 :::
 209
 210 ::: incorrect
 211
 212 ```js
 213 /* eslint spaced-comment: ["error", "always", { "exceptions": ["-", "+"] }] */
 214
 215 /*------++++++++*/
 216 /* Comment block */
 217 /*------++++++++*/
 218 ```
 219
 220 :::
 221
 222 ::: incorrect
 223
 224 ```js
 225 /* eslint spaced-comment: ["error", "always", { "line": { "exceptions": ["-+"] } }] */
 226
 227 /*-+-+-+-+-+-+-+*/
 228 // Comment block
 229 /*-+-+-+-+-+-+-+*/
 230 ```
 231
 232 :::
 233
 234 ::: incorrect
 235
 236 ```js
 237 /* eslint spaced-comment: ["error", "always", { "block": { "exceptions": ["*"] } }] */
 238
 239 /******** COMMENT *******/
 240 ```
 241
 242 :::
 243
 244 Examples of **correct** code for this rule with the `"always"` option combined with `"exceptions"`:
 245
 246 ::: correct
 247
 248 ```js
 249 /* eslint spaced-comment: ["error", "always", { "exceptions": ["-"] }] */
 250
 251 //--------------
 252 // Comment block
 253 //--------------
 254 ```
 255
 256 :::
 257
 258 ::: correct
 259
 260 ```js
 261 /* eslint spaced-comment: ["error", "always", { "line": { "exceptions": ["-"] } }] */
 262
 263 //--------------
 264 // Comment block
 265 //--------------
 266 ```
 267
 268 :::
 269
 270 ::: correct
 271
 272 ```js
 273 /* eslint spaced-comment: ["error", "always", { "exceptions": ["*"] }] */
 274
 275 /****************
 276  * Comment block
 277  ****************/
 278 ```
 279
 280 :::
 281
 282 ::: correct
 283
 284 ```js
 285 /* eslint spaced-comment: ["error", "always", { "exceptions": ["-+"] }] */
 286
 287 //-+-+-+-+-+-+-+
 288 // Comment block
 289 //-+-+-+-+-+-+-+
 290
 291 /*-+-+-+-+-+-+-+*/
 292 // Comment block
 293 /*-+-+-+-+-+-+-+*/
 294 ```
 295
 296 :::
 297
 298 ::: correct
 299
 300 ```js
 301 /* eslint spaced-comment: ["error", "always", { "block": { "exceptions": ["-+"] } }] */
 302
 303 /*-+-+-+-+-+-+-+*/
 304 // Comment block
 305 /*-+-+-+-+-+-+-+*/
 306 ```
 307
 308 :::
 309
 310 ::: correct
 311
 312 ```js
 313 /* eslint spaced-comment: ["error", "always", { "block": { "exceptions": ["*"] } }] */
 314
 315 /***************/
 316
 317 /********
 318 COMMENT
 319 *******/
 320 ```
 321
 322 :::
 323
 324 ### markers
 325
 326 Examples of **incorrect** code for this rule with the `"always"` option combined with `"markers"`:
 327
 328 ::: incorrect
 329
 330 ```js
 331 /* eslint spaced-comment: ["error", "always", { "markers": ["/"] }] */
 332
 333 ///This is a comment with a marker but without whitespace
 334 ```
 335
 336 :::
 337
 338 ::: incorrect
 339
 340 ```js
 341 /*eslint spaced-comment: ["error", "always", { "block": { "markers": ["!"], "balanced": true } }]*/
 342 /*! This is a comment with a marker but without whitespace at the end*/
 343 ```
 344
 345 :::
 346
 347 ::: incorrect
 348
 349 ```js
 350 /*eslint spaced-comment: ["error", "never", { "block": { "markers": ["!"], "balanced": true } }]*/
 351 /*!This is a comment with a marker but with whitespace at the end */
 352 ```
 353
 354 :::
 355
 356 Examples of **correct** code for this rule with the `"always"` option combined with `"markers"`:
 357
 358 ::: correct
 359
 360 ```js
 361 /* eslint spaced-comment: ["error", "always", { "markers": ["/"] }] */
 362
 363 /// This is a comment with a marker
 364 ```
 365
 366 :::
 367
 368 ::: correct
 369
 370 ```js
 371 /*eslint spaced-comment: ["error", "never", { "markers": ["!<"] }]*/
 372
 373 //!<This is a line comment with a marker
 374
 375 /*!<this is a block comment with a marker
 376 subsequent lines are ignored
 377 */
 378 ```
 379
 380 :::
 381
 382 ::: correct
 383
 384 ```js
 385 /* eslint spaced-comment: ["error", "always", { "markers": ["global"] }] */
 386
 387 /*global ABC*/
 388 ```
 389
 390 :::