1======================= 2JavaScript Coding style 3======================= 4 5Coding style 6~~~~~~~~~~~~ 7 8`prettier <https://prettier.io/>`_ is the tool used to reformat the JavaScript code. 9 10 11Methods and functions 12~~~~~~~~~~~~~~~~~~~~~ 13 14In JavaScript, functions should use camelCase, but should not capitalize 15the first letter. Methods should not use the named function expression 16syntax, because our tools understand method names: 17 18.. code-block:: cpp 19 20 doSomething: function (aFoo, aBar) { 21 ... 22 } 23 24In-line functions should have spaces around braces, except before commas 25or semicolons: 26 27.. code-block:: cpp 28 29 function valueObject(aValue) { return { value: aValue }; } 30 31 32JavaScript objects 33~~~~~~~~~~~~~~~~~~ 34 35.. code-block:: cpp 36 37 var foo = { prop1: "value1" }; 38 39 var bar = { 40 prop1: "value1", 41 prop2: "value2" 42 }; 43 44Constructors for objects should be capitalized and use Pascal Case: 45 46.. code-block:: cpp 47 48 function ObjectConstructor() { 49 this.foo = "bar"; 50 } 51 52 53Operators 54~~~~~~~~~ 55 56In JavaScript, overlong expressions not joined by ``&&`` and 57``||`` should break so the operator starts on the second line and 58starting in the same column as the beginning of the expression in the 59first line. This applies to ``?:``, binary arithmetic operators 60including ``+``, and member-of operators. Rationale: an operator at the 61front of the continuation line makes for faster visual scanning, as 62there is no need to read to the end of line. Also there exists a 63context-sensitive keyword hazard in JavaScript; see {{bug(442099, "bug", 6419)}}, which can be avoided by putting . at the start of a continuation 65line, in long member expression. 66 67In JavaScript, ``==`` is preferred to ``===``. 68 69Unary keyword operators, such as ``typeof``, should have their operand 70parenthesized; e.g. ``typeof("foo") == "string"``. 71 72Literals 73~~~~~~~~ 74 75Double-quoted strings (e.g. ``"foo"``) are preferred to single-quoted 76strings (e.g. ``'foo'``), in JavaScript, except to avoid escaping 77embedded double quotes, or when assigning inline event handlers. 78 79 80Prefixes 81~~~~~~~~ 82 83- k=constant (e.g. ``kNC_child``). Not all code uses this style; some 84 uses ``ALL_CAPS`` for constants. 85- g=global (e.g. ``gPrefService``) 86- a=argument (e.g. ``aCount``) 87 88- JavaScript Specific Prefixes 89 90 - \_=member (variable or function) (e.g. ``_length`` or 91 ``_setType(aType)``) 92 - k=enumeration value (e.g. ``const kDisplayModeNormal = 0``) 93 - on=event handler (e.g. ``function onLoad()``) 94 - Convenience constants for interface names should be prefixed with 95 ``nsI``: 96 97 .. code-block:: javascript 98 99 const nsISupports = Components.interfaces.nsISupports; 100 const nsIWBN = Components.interfaces.nsIWebBrowserNavigation; 101 102 103 104Other advices 105~~~~~~~~~~~~~ 106 107- Make sure you are aware of the `JavaScript 108 Tips <https://developer.mozilla.org/docs/Mozilla/JavaScript_Tips>`__. 109- Do not compare ``x == true`` or ``x == false``. Use ``(x)`` or 110 ``(!x)`` instead. ``x == true``, is certainly different from if 111 ``(x)``! Compare objects to ``null``, numbers to ``0`` or strings to 112 ``""``, if there is chance for confusion. 113- Make sure that your code doesn't generate any strict JavaScript 114 warnings, such as: 115 116 - Duplicate variable declaration. 117 - Mixing ``return;`` with ``return value;`` 118 - Undeclared variables or members. If you are unsure if an array 119 value exists, compare the index to the array's length. If you are 120 unsure if an object member exists, use ``"name"`` in ``aObject``, 121 or if you are expecting a particular type you may use 122 ``typeof(aObject.name) == "function"`` (or whichever type you are 123 expecting). 124 125- Use ``['value1, value2']`` to create a JavaScript array in preference 126 to using 127 ``new {{JSxRef("Array", "Array", "Syntax", 1)}}(value1, value2)`` 128 which can be confusing, as ``new Array(length)`` will actually create 129 a physically empty array with the given logical length, while 130 ``[value]`` will always create a 1-element array. You cannot actually 131 guarantee to be able to preallocate memory for an array. 132- Use ``{ member: value, ... }`` to create a JavaScript object; a 133 useful advantage over ``new {{JSxRef("Object", "Object", "", 1)}}()`` 134 is the ability to create initial properties and use extended 135 JavaScript syntax, to define getters and setters. 136- If having defined a constructor you need to assign default 137 properties, it is preferred to assign an object literal to the 138 prototype property. 139- Use regular expressions, but use wisely. For instance, to check that 140 ``aString`` is not completely whitespace use 141 ``/\S/.{{JSxRef("RegExp.test", "test(aString)", "", 1)}}``. Only use 142 {{JSxRef("String.search", "aString.search()")}} if you need to know 143 the position of the result, or {{JSxRef("String.match", 144 "aString.match()")}} if you need to collect matching substrings 145 (delimited by parentheses in the regular expression). Regular 146 expressions are less useful if the match is unknown in advance, or to 147 extract substrings in known positions in the string. For instance, 148 {{JSxRef("String.slice", "aString.slice(-1)")}} returns the last 149 letter in ``aString``, or the empty string if ``aString`` is empty. 150