eslint/docs/rules/no-underscore-dangle.md

   1 # disallow dangling underscores in identifiers (no-underscore-dangle)
   2
   3 As far as naming conventions for identifiers go, dangling underscores may be the most polarizing in JavaScript. Dangling underscores are underscores at either the beginning or end of an identifier, such as:
   4
   5 ```js
   6 var _foo;
   7 ```
   8
   9 There is actually a long history of using dangling underscores to indicate "private" members of objects in JavaScript (though JavaScript doesn't have truly private members, this convention served as a warning). This began with SpiderMonkey adding nonstandard methods such as `__defineGetter__()`. The intent with the underscores was to make it obvious that this method was special in some way. Since that time, using a single underscore prefix has become popular as a way to indicate "private" members of objects.
  10
  11 Whether or not you choose to allow dangling underscores in identifiers is purely a convention and has no effect on performance, readability, or complexity. It's purely a preference.
  12
  13 ## Rule Details
  14
  15 This rule disallows dangling underscores in identifiers.
  16
  17 Examples of **incorrect** code for this rule:
  18
  19 ```js
  20 /*eslint no-underscore-dangle: "error"*/
  21
  22 var foo_;
  23 var __proto__ = {};
  24 foo._bar();
  25 ```
  26
  27 Examples of **correct** code for this rule:
  28
  29 ```js
  30 /*eslint no-underscore-dangle: "error"*/
  31
  32 var _ = require('underscore');
  33 var obj = _.contains(items, item);
  34 obj.__proto__ = {};
  35 var file = __filename;
  36 function foo(_bar) {};
  37 const foo = { onClick(_bar) {} };
  38 const foo = (_bar) => {};
  39 ```
  40
  41 ## Options
  42
  43 This rule has an object option:
  44
  45 -  `"allow"` allows specified identifiers to have dangling underscores
  46 -  `"allowAfterThis": false` (default) disallows dangling underscores in members of the `this` object
  47 -  `"allowAfterSuper": false` (default) disallows dangling underscores in members of the `super` object
  48 -  `"allowAfterThisConstructor": false` (default) disallows dangling underscores in members of the `this.constructor` object
  49 -  `"enforceInMethodNames": false` (default) allows dangling underscores in method names
  50 -  `"allowFunctionParams": true` (default) allows dangling underscores in function parameter names
  51
  52 ### allow
  53
  54 Examples of additional **correct** code for this rule with the `{ "allow": ["foo_", "_bar"] }` option:
  55
  56 ```js
  57 /*eslint no-underscore-dangle: ["error", { "allow": ["foo_", "_bar"] }]*/
  58
  59 var foo_;
  60 foo._bar();
  61 ```
  62
  63 ### allowAfterThis
  64
  65 Examples of **correct** code for this rule with the `{ "allowAfterThis": true }` option:
  66
  67 ```js
  68 /*eslint no-underscore-dangle: ["error", { "allowAfterThis": true }]*/
  69
  70 var a = this.foo_;
  71 this._bar();
  72 ```
  73
  74 ### allowAfterSuper
  75
  76 Examples of **correct** code for this rule with the `{ "allowAfterSuper": true }` option:
  77
  78 ```js
  79 /*eslint no-underscore-dangle: ["error", { "allowAfterSuper": true }]*/
  80
  81 var a = super.foo_;
  82 super._bar();
  83 ```
  84
  85 ### allowAfterThisConstructor
  86
  87 Examples of **correct** code for this rule with the `{ "allowAfterThisConstructor": true }` option:
  88
  89 ```js
  90 /*eslint no-underscore-dangle: ["error", { "allowAfterThisConstructor": true }]*/
  91
  92 var a = this.constructor.foo_;
  93 this.constructor._bar();
  94 ```
  95
  96 ### enforceInMethodNames
  97
  98 Examples of **incorrect** code for this rule with the `{ "enforceInMethodNames": true }` option:
  99
 100 ```js
 101 /*eslint no-underscore-dangle: ["error", { "enforceInMethodNames": true }]*/
 102
 103 class Foo {
 104   _bar() {}
 105 }
 106
 107 class Foo {
 108   bar_() {}
 109 }
 110
 111 const o = {
 112   _bar() {}
 113 };
 114
 115 const o = {
 116   bar_() = {}
 117 };
 118 ```
 119
 120 ### allowFunctionParams
 121
 122 Examples of **incorrect** code for this rule with the `{ "allowFunctionParams": false }` option:
 123
 124 ```js
 125 /*eslint no-underscore-dangle: ["error", { "allowFunctionParams": false }]*/
 126
 127 function foo (_bar) {}
 128 function foo (_bar = 0) {}
 129 function foo (..._bar) {}
 130
 131 const foo = function onClick (_bar) {}
 132 const foo = function onClick (_bar = 0) {}
 133 const foo = function onClick (..._bar) {}
 134
 135 const foo = (_bar) => {};
 136 const foo = (_bar = 0) => {};
 137 const foo = (..._bar) => {};
 138 ```
 139
 140 ## When Not To Use It
 141
 142 If you want to allow dangling underscores in identifiers, then you can safely turn this rule off.