eslint/docs/rules/capitalized-comments.md

   1 # enforce or disallow capitalization of the first letter of a comment (capitalized-comments)
   2
   3 Comments are useful for leaving information for future developers. In order for that information to be useful and not distracting, it is sometimes desirable for comments to follow a particular style. One element of comment formatting styles is whether the first word of a comment should be capitalized or lowercase.
   4
   5 In general, no comment style is any more or less valid than any others, but many developers would agree that a consistent style can improve a project's maintainability.
   6
   7 ## Rule Details
   8
   9 This rule aims to enforce a consistent style of comments across your codebase, specifically by either requiring or disallowing a capitalized letter as the first word character in a comment. This rule will not issue warnings when non-cased letters are used.
  10
  11 By default, this rule will require a non-lowercase letter at the beginning of comments.
  12
  13 Examples of **incorrect** code for this rule:
  14
  15 ```js
  16 /* eslint capitalized-comments: ["error"] */
  17
  18 // lowercase comment
  19
  20 ```
  21
  22 Examples of **correct** code for this rule:
  23
  24 ```js
  25
  26 // Capitalized comment
  27
  28 // 1. Non-letter at beginning of comment
  29
  30 // 丈 Non-Latin character at beginning of comment
  31
  32 /* eslint semi:off */
  33 /* eslint-env node */
  34 /* eslint-disable */
  35 /* eslint-enable */
  36 /* istanbul ignore next */
  37 /* jscs:enable */
  38 /* jshint asi:true */
  39 /* global foo */
  40 /* globals foo */
  41 /* exported myVar */
  42 // eslint-disable-line
  43 // eslint-disable-next-line
  44 // https://github.com
  45
  46 ```
  47
  48 ### Options
  49
  50 This rule has two options: a string value `"always"` or `"never"` which determines whether capitalization of the first word of a comment should be required or forbidden, and optionally an object containing more configuration parameters for the rule.
  51
  52 Here are the supported object options:
  53
  54 * `ignorePattern`: A string representing a regular expression pattern of words that should be ignored by this rule. If the first word of a comment matches the pattern, this rule will not report that comment.
  55     * Note that the following words are always ignored by this rule: `["jscs", "jshint", "eslint", "istanbul", "global", "globals", "exported"]`.
  56 * `ignoreInlineComments`: If this is `true`, the rule will not report on comments in the middle of code. By default, this is `false`.
  57 * `ignoreConsecutiveComments`: If this is `true`, the rule will not report on a comment which violates the rule, as long as the comment immediately follows another comment. By default, this is `false`.
  58
  59 Here is an example configuration:
  60
  61 ```json
  62 {
  63     "capitalized-comments": [
  64         "error",
  65         "always",
  66         {
  67             "ignorePattern": "pragma|ignored",
  68             "ignoreInlineComments": true
  69         }
  70     ]
  71 }
  72 ```
  73
  74 #### `"always"`
  75
  76 Using the `"always"` option means that this rule will report any comments which start with a lowercase letter. This is the default configuration for this rule.
  77
  78 Note that configuration comments and comments which start with URLs are never reported.
  79
  80 Examples of **incorrect** code for this rule:
  81
  82 ```js
  83 /* eslint capitalized-comments: ["error", "always"] */
  84
  85 // lowercase comment
  86
  87 ```
  88
  89 Examples of **correct** code for this rule:
  90
  91 ```js
  92 /* eslint capitalized-comments: ["error", "always"] */
  93
  94 // Capitalized comment
  95
  96 // 1. Non-letter at beginning of comment
  97
  98 // 丈 Non-Latin character at beginning of comment
  99
 100 /* eslint semi:off */
 101 /* eslint-env node */
 102 /* eslint-disable */
 103 /* eslint-enable */
 104 /* istanbul ignore next */
 105 /* jscs:enable */
 106 /* jshint asi:true */
 107 /* global foo */
 108 /* globals foo */
 109 /* exported myVar */
 110 // eslint-disable-line
 111 // eslint-disable-next-line
 112 // https://github.com
 113
 114 ```
 115
 116 #### `"never"`
 117
 118 Using the `"never"` option means that this rule will report any comments which start with an uppercase letter.
 119
 120 Examples of **incorrect** code with the `"never"` option:
 121
 122 ```js
 123 /* eslint capitalized-comments: ["error", "never"] */
 124
 125 // Capitalized comment
 126
 127 ```
 128
 129 Examples of **correct** code with the `"never"` option:
 130
 131 ```js
 132 /* eslint capitalized-comments: ["error", "never"] */
 133
 134 // lowercase comment
 135
 136 // 1. Non-letter at beginning of comment
 137
 138 // 丈 Non-Latin character at beginning of comment
 139
 140 ```
 141
 142 #### `ignorePattern`
 143
 144 The `ignorePattern` object takes a string value, which is used as a regular expression applied to the first word of a comment.
 145
 146 Examples of **correct** code with the `"ignorePattern"` option set to `"pragma"`:
 147
 148 ```js
 149 /* eslint capitalized-comments: ["error", "always", { "ignorePattern": "pragma" }] */
 150
 151 function foo() {
 152     /* pragma wrap(true) */
 153 }
 154
 155 ```
 156
 157 #### `ignoreInlineComments`
 158
 159 Setting the `ignoreInlineComments` option to `true` means that comments in the middle of code (with a token on the same line as the beginning of the comment, and another token on the same line as the end of the comment) will not be reported by this rule.
 160
 161 Examples of **correct** code with the `"ignoreInlineComments"` option set to `true`:
 162
 163 ```js
 164 /* eslint capitalized-comments: ["error", "always", { "ignoreInlineComments": true }] */
 165
 166 function foo(/* ignored */ a) {
 167 }
 168
 169 ```
 170
 171 #### `ignoreConsecutiveComments`
 172
 173 If the `ignoreConsecutiveComments` option is set to `true`, then comments which otherwise violate the rule will not be reported as long as they immediately follow another comment. This can be applied more than once.
 174
 175 Examples of **correct** code with `ignoreConsecutiveComments` set to `true`:
 176
 177 ```js
 178 /* eslint capitalized-comments: ["error", "always", { "ignoreConsecutiveComments": true }] */
 179
 180 // This comment is valid since it has the correct capitalization.
 181 // this comment is ignored since it follows another comment,
 182 // and this one as well because it follows yet another comment.
 183
 184 /* Here is a block comment which has the correct capitalization, */
 185 /* but this one is ignored due to being consecutive; */
 186 /*
 187  * in fact, even if any of these are multi-line, that is fine too.
 188  */
 189 ```
 190
 191 Examples of **incorrect** code with `ignoreConsecutiveComments` set to `true`:
 192
 193 ```js
 194 /* eslint capitalized-comments: ["error", "always", { "ignoreConsecutiveComments": true }] */
 195
 196 // this comment is invalid, but only on this line.
 197 // this comment does NOT get reported, since it is a consecutive comment.
 198 ```
 199
 200 ### Using Different Options for Line and Block Comments
 201
 202 If you wish to have a different configuration for line comments and block comments, you can do so by using two different object configurations (note that the capitalization option will be enforced consistently for line and block comments):
 203
 204 ```json
 205 {
 206     "capitalized-comments": [
 207         "error",
 208         "always",
 209         {
 210             "line": {
 211                 "ignorePattern": "pragma|ignored",
 212             },
 213             "block": {
 214                 "ignoreInlineComments": true,
 215                 "ignorePattern": "ignored"
 216             }
 217         }
 218     ]
 219 }
 220 ```
 221
 222 Examples of **incorrect** code with different line and block comment configuration:
 223
 224 ```js
 225 /* eslint capitalized-comments: ["error", "always", { "block": { "ignorePattern": "blockignore" } }] */
 226
 227 // capitalized line comment, this is incorrect, blockignore does not help here
 228 /* lowercased block comment, this is incorrect too */
 229
 230 ```
 231
 232 Examples of **correct** code with different line and block comment configuration:
 233
 234 ```js
 235 /* eslint capitalized-comments: ["error", "always", { "block": { "ignorePattern": "blockignore" } }] */
 236
 237 // Uppercase line comment, this is correct
 238 /* blockignore lowercase block comment, this is correct due to ignorePattern */
 239
 240 ```
 241
 242 ## When Not To Use It
 243
 244 This rule can be disabled if you do not care about the grammatical style of comments in your codebase.
 245
 246 ## Compatibility
 247
 248 * **JSCS**: [requireCapitalizedComments](https://jscs-dev.github.io/rule/requireCapitalizedComments)
 249 * **JSCS**: [disallowCapitalizedComments](https://jscs-dev.github.io/rule/disallowCapitalizedComments)