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

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