xmpp.chapril.org-conversejs/docs/source/style_guide.rst

166 lines
3.8 KiB
ReStructuredText
Raw Normal View History

2016-11-02 15:31:58 +01:00
.. raw:: html
2022-06-08 11:10:04 +02:00
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/style_guide.rst">Edit me on GitHub</a></div>
2016-11-02 15:31:58 +01:00
Software Style Guide
====================
Most of the style guide recommendations here come from Douglas Crockford's book
2017-09-03 22:12:17 +02:00
`JavaScript, the good parts <http://shop.oreilly.com/product/9780596517748.do>`_
Tabs or spaces?
---------------
2022-03-29 22:55:48 +02:00
We always indent 4 spaces.
Underscores or camelCase?
-------------------------
We use camelCase for function names and underscores for variables names.
For example:
.. code-block:: javascript
function thisIsAFunction () {
let this_is_a_variable;
...
}
2022-03-29 22:55:48 +02:00
const versus let
----------------
Try to use `const` whenever possible. If a variable won't be reassigned, use
`const`, otherwise use `let`.
2015-06-19 17:54:49 +02:00
Spaces around operators
-----------------------
In general, spaces are put around operators, such as the equals ``=`` or plus ``+`` signs.
For example:
.. code-block:: javascript
2015-06-19 17:54:49 +02:00
if (sublocale != locale) {
// do something
}
An exception is when they appear inside for-loop expressions, for example:
.. code-block:: javascript
2015-06-19 17:54:49 +02:00
for (i=0; i<msgs_length; i++) {
// do something
}
Generally though, rather err on the side of adding spaces, since they make the
code much more readable.
2022-03-29 22:55:48 +02:00
destructuring
-------------
When assigning to a variable via destructuring, add spaces between the curly
brackets.
For example:
.. code-block:: javascript
const { foo } = bar;
Global constants are written in ALL_CAPS
----------------------------------------
Global identifiers that denote constant values should be written in
all capital letters, with underscores between words.
For example:
.. code-block:: javascript
const SECONDS_IN_HOUR = 3600;
function update () {
const timeout = 20;
let seconds_since_message = 0;
// other stuff here
}
Function declaration and invocation
-----------------------------------
When declaring a function, the function name and the brackets after it are separated
with a space. Like so:
.. code-block:: javascript
function update (model) {
model.foo = 'bar';
}
When calling the same function, the brackets are written without a space in
between:
.. code-block:: javascript
update(model);
This is to make a more explicit visual distinction between method declarations
and method invocations.
Checking for equality
---------------------
2017-09-03 22:12:17 +02:00
JavaScript has a strict ``===`` and less strict ``==`` equality operator. The
stricter equality operator also does type checking. To avoid subtle bugs when
doing comparisons, always use the strict equality check.
2015-06-19 17:54:49 +02:00
Curly brackets
--------------
Curly brackets must appear on the same lines as the ``if`` and ``else`` keywords.
The closing curly bracket appears on its own line.
2015-06-19 17:54:49 +02:00
For example:
.. code-block:: javascript
2015-06-19 17:54:49 +02:00
if (locales[locale]) {
return locales[locale];
} else {
sublocale = locale.split("-")[0];
if (sublocale != locale && locales[sublocale]) {
return locales[sublocale];
}
}
Always enclose blocks in curly brackets
2015-06-19 17:54:49 +02:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When writing a block such as an ``if`` or ``while`` statement, always use
curly brackets around that block of code. Even when not strictly required by
the compiler (for example if its only one line inside the ``if`` statement).
For example, like this:
.. code-block:: javascript
if (condition === true) {
this.updateRoomsList();
}
somethingElse();
and NOT like this:
.. code-block:: javascript
if (converse.auto_list_rooms)
this.updateRoomsList();
somethingElse();
This is to aid in readability and to avoid subtle bugs where certain lines are
wrongly assumed to be executed within a block.