eslint/docs/rules/no-warning-comments.md

   1 # Disallow Warning Comments (no-warning-comments)
   2
   3 Developers often add comments to code which is not complete or needs review. Most likely you want to fix or review the code, and then remove the comment, before you consider the code to be production ready.
   4
   5 ```js
   6 // TODO: do something
   7 // FIXME: this is not a good idea
   8 ```
   9
  10 ## Rule Details
  11
  12 This rule reports comments that include any of the predefined terms specified in its configuration.
  13
  14 ## Options
  15
  16 This rule has an options object literal:
  17
  18 * `"terms"`: optional array of terms to match. Defaults to `["todo", "fixme", "xxx"]`. Terms are matched case-insensitive and as whole words: `fix` would match `FIX` but not `fixing`. Terms can consist of multiple words: `really bad idea`.
  19 * `"location"`: optional string that configures where in your comments to check for matches. Defaults to `"start"`. The other value is match `anywhere` in comments.
  20
  21 Example of **incorrect** code for the default `{ "terms": ["todo", "fixme", "xxx"], "location": "start" }` options:
  22
  23 ```js
  24 /*eslint no-warning-comments: "error"*/
  25
  26 function callback(err, results) {
  27   if (err) {
  28     console.error(err);
  29     return;
  30   }
  31   // TODO
  32 }
  33 ```
  34
  35 Example of **correct** code for the default `{ "terms": ["todo", "fixme", "xxx"], "location": "start" }` options:
  36
  37 ```js
  38 /*eslint no-warning-comments: "error"*/
  39
  40 function callback(err, results) {
  41   if (err) {
  42     console.error(err);
  43     return;
  44   }
  45   // NOT READY FOR PRIME TIME
  46   // but too bad, it is not a predefined warning term
  47 }
  48 ```
  49
  50 ### terms and location
  51
  52 Examples of **incorrect** code for the `{ "terms": ["todo", "fixme", "any other term"], "location": "anywhere" }` options:
  53
  54 ```js
  55 /*eslint no-warning-comments: ["error", { "terms": ["todo", "fixme", "any other term"], "location": "anywhere" }]*/
  56
  57 // TODO: this
  58 // todo: this too
  59 // Even this: TODO
  60 /* /*
  61  * The same goes for this TODO comment
  62  * Or a fixme
  63  * as well as any other term
  64  */
  65 ```
  66
  67 Examples of **correct** code for the `{ "terms": ["todo", "fixme", "any other term"], "location": "anywhere" }` options:
  68
  69 ```js
  70 /*eslint no-warning-comments: ["error", { "terms": ["todo", "fixme", "any other term"], "location": "anywhere" }]*/
  71
  72 // This is to do
  73 // even not any other    term
  74 // any other terminal
  75 /*
  76  * The same goes for block comments
  77  * with any other interesting term
  78  * or fix me this
  79  */
  80 ```
  81
  82 ## When Not To Use It
  83
  84 * If you have a large code base that was not developed with a policy to not use such warning terms, you might get hundreds of warnings / errors which might be counter-productive if you can't fix all of them (e.g. if you don't get the time to do it) as you might overlook other warnings / errors or get used to many of them and don't pay attention on it anymore.
  85 * Same reason as the point above: You shouldn't configure terms that are used very often (e.g. central parts of the native language used in your comments).