eslint/docs/rules/spaced-comment.md

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