116 lines
3.9 KiB
ReStructuredText
116 lines
3.9 KiB
ReStructuredText
Matrix JavaScript/ECMAScript Style Guide
|
|
========================================
|
|
|
|
The intention of this guide is to make Matrix's JavaScript codebase clean,
|
|
consistent with other popular JavaScript styles and consistent with the rest of
|
|
the Matrix codebase. For reference, the Matrix Python style guide can be found
|
|
at https://github.com/matrix-org/synapse/blob/master/docs/code_style.rst
|
|
|
|
General Style
|
|
-------------
|
|
|
|
- 4 spaces to indent, for consistency with Matrix Python.
|
|
- Max line width: 79 chars (with flexibility to overflow by a "few chars" if
|
|
the overflowing content is not semantically significant and avoids an
|
|
explosion of vertical whitespace).
|
|
- No trailing whitespace at end of lines.
|
|
- Don't indent empty lines.
|
|
- One newline at the end of the file.
|
|
- Unix newlines, never `\r`
|
|
- Indent similar to our python code: break up long lines at logical boundaries,
|
|
more than one argument on a line is OK
|
|
- Use semicolons, for consistency with node.
|
|
- UpperCamelCase for class and type names
|
|
- lowerCamelCase for functions and variables.
|
|
- Single line ternary operators are fine.
|
|
- UPPER_CAMEL_CASE for constants
|
|
- Single quotes for strings, for consistency with most JavaScript styles::
|
|
"bad" // Bad
|
|
'good' // Good
|
|
- Use parentheses instead of '\\' for line continuation where ever possible
|
|
- Open braces on the same line (consistent with Node)::
|
|
if (x) {
|
|
console.log("I am a fish"); // Good
|
|
}
|
|
|
|
if (x)
|
|
{
|
|
console.log("I am a fish"); // Bad
|
|
}
|
|
- Spaces after `if`, `for`, `else` etc, no space around the condition::
|
|
if (x) {
|
|
console.log("I am a fish"); // Good
|
|
}
|
|
|
|
if(x) {
|
|
console.log("I am a fish"); // Bad
|
|
}
|
|
|
|
if ( x ) {
|
|
console.log("I am a fish"); // Bad
|
|
}
|
|
- Declare one variable per var statement (consistent with Node). Unless they
|
|
are simple and closely related. If you put the next declaration on a new line,
|
|
treat yourself to another `var`::
|
|
var key = "foo",
|
|
comparator = function(x, y) {
|
|
return x - y;
|
|
}; // Bad
|
|
|
|
var key = "foo";
|
|
var comparator = function(x, y) {
|
|
return x - y;
|
|
}; // Good
|
|
|
|
var x = 0, y = 0; // Fine
|
|
|
|
var x = 0;
|
|
var y = 0; // Also fine
|
|
- A single line `if` is fine, all others have braces. This prevents errors when adding to the code.::
|
|
if (x) return true; // Fine
|
|
|
|
if (x) {
|
|
return true; // Also fine
|
|
}
|
|
|
|
if (x)
|
|
return true; // Not fine
|
|
- Terminate all multi-line lists with commas::
|
|
var mascots = [
|
|
"Patrick",
|
|
"Shirley",
|
|
"Colin",
|
|
"Susan",
|
|
"Sir Arthur David" // Bad
|
|
];
|
|
|
|
var mascots = [
|
|
"Patrick",
|
|
"Shirley",
|
|
"Colin",
|
|
"Susan",
|
|
"Sir Arthur David", // Good
|
|
];
|
|
- Use `null`, `undefined` etc consistently with node:
|
|
Boolean variables and functions should always be either true or false. Don't set it to 0 unless it's supposed to be a number.
|
|
When something is intentionally missing or removed, set it to null.
|
|
Don't set things to undefined. Reserve that value to mean "not yet set to anything."
|
|
Boolean objects are verboten.
|
|
- Use JSDoc
|
|
|
|
ECMAScript
|
|
----------
|
|
- Use `let` for variables and `const` for constants. This sounds obvious, but it isn't: the ES6 `const` keyword
|
|
could be used for assign-once variables, however this guide advises against doing so on the grounds that it
|
|
confuses them with constants.
|
|
- Be careful migrating files to newer syntax.
|
|
- Don't mix `require` and `import` in the same file. Either stick to the old style or change them all.
|
|
- Likewise, don't mix things like class properties and `MyClass.prototype.MY_CONSTANT = 42;`
|
|
- Be careful mixing arrow functions and regular functions, eg. if one function in a promise chain is an
|
|
arrow function, they probably all should be.
|
|
- Apart from that, newer ES features should be used whenever the author deems them to be appropriate.
|
|
- Flow annotations are welcome and encouraged.
|
|
|
|
React
|
|
-----
|
|
- Use ES6 classes, although bear in mind a lot of code uses createClass.
|