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