The JavaScript style used in the code is a modernized version of the style used in The C Programming Language.
In the great tabs vs. spaces debate, this code falls on the tabs side, as this represent the actual semantics. Tabs are set to 2 spaces.
In most cases, in-line comments should start at column 41, where possible.
Multi-word variable names are specified using camelCase. Small names may be used in very local contexts (e.g., using i for a loop count). Use larger more readable names in larger contexts. Try to avoid abbreviations or contractions. However, they may be used where the meaning is clear, and the variable name would be ridiculously long without it.
Constants are not required to be in all caps. Use your judgment.
Try to define variables near where they are used.
Lines should be 80 characters or less. If possible, subexpressions that continue on another line should be indented from the first line and begin with an operator (not a comma), if possible. This aids in scanning code where the eye normally intuits the structure by looking at the lefthand indentation. Having an operator there makes the structure clear while scanning.
Binary operators should have spacing between the operator and the arguments. However, when + is used for string concatenation there should be no space to distinguish the intent from addition visually. For example:
newString = oldString+'ing';
Long ternary operators should be split as follows:
const foo = (
condition
? result1
: result2
);
Multi-level ternary operators should be stlyes as follows:
const foo = (
condition1 ? result1
: condition2 ? result2
: result3
);
Unary operators that are keywords instead of a single special character, such as return or throw, should have the argument enclosed in parens and separated by a space. For example:
return (value);
This visually distinguishes the unary operator keyword from a variable name and function invocation.
The cases for a switch statement are aligned with the switch:
switch (foo) {
case 1:
...
break;
case 2:
...
break;
default:
...
break;
}
A function definition has a space between the function name and the open parenthesis for the arguments. A function invocation has no space. This visually distinguishes the two.
// defintion
function foo (arg1) {
}
// invocation
foo(3);
Use parens around a single arrow-function argument when the arrow function is being assigned. This avoids visual confusion with the "=" signs:
const foo = (arg1) => (arg1 + 2);
Otherwise, parens around an arrow function argument are not required:
newArray = oldArray.map(elt => elt.value);
To be added.
To be added.
The layout of most Markdown documents in the doc/ directory is as follows:
<!-- toc opts:h2,h3 -->
# Document title
## Related documents
* [Document 1](document1.md)
* [Document 2](document2.md)
...
## Table of contents
<!-- toc start -->
<!-- toc end -->
---
## Heading 1
...
The Table of Contents is automatically generated and is placed between the <!-- toc start --> and <!-- toc end --> lines. By default, all heading are included except if they have at the end. Adding to the end of a heading will prevent that heading from being referenced in the Table of Contents. You can also specify a <!-- toc opts:h2,h3 --> line which limits the indexed headings to the specified numeric levels after the 'h'.
The generated index is indexed both alphabetically and categorically. You can add an index target by adding the following line to the Markdown:
!-- myTarget: index:myCategory:mySubCategory -->
The myTarget string appears in the index as a hyperlink to this file. In the categorical index, it appears as a hyperlink under myCategory and mySubCategory. Here's an example of the Ptable class:
<!-- target="`Ptable`" index="Classes:Aeronautical classes" -->
It's OK to have more than one index target in a file.
A specific heading can be target in the index as follows:
## myHeading <!-- index="myCategory:mySubCategory" -->
This will add myHeading as a hyperlink in the alphabetical index and the categorical index under mySubCategory, which is, in turn, under myCategory. When clicked, the link will go directly to the heading. The level of the heading is immaterial.
In general, code documentation should follow an MDN-like style. Each function or method should have a heading that contains the function or method name followed by opening and closing parens and surrounded by backticks:
### `myInstanceMethod()`
Static and singleton object methods should include the class or object name in the heading:
### `myClass.myStaticMethod()`
Class and singleton object methods are indexed under the class or singleton object. Independent function should have an index target appended:
### `myFunction()` <!-- index="myCategory:mySubCategory" -->
The heading should be followed by a syntax sub-heading not automatically indexed in the table of contents (e.g., heading level 4). The heading is followed by a code block giving the various ways the function or method can be invoked:
#### Syntax
```JavaScript
myFunction(arg1)
myFunction(arg1, arg2)
```
Static and singleton object methods should include the class or object name:
#### Syntax
```JavaScript
myObject.myMethod(arg1)
myObject.myMethod(arg1, arg2)
```
A general function explanation follows the code block in the syntax section. This may include usage examples.
If the function or method has parameters then a non-indexed parameters sub-section follows the explanation. Each parameter should be in a list with an explanation following each parameter. The parameter name should be surrounded by backticks. Optional arguments should be noted:
#### Parameters
* `arg1`
Explanation for `arg1`.
* `arg2` (optional)
Explanation for `arg1`.
If the function or method returns a value than a non-indexed return value sub-section follows:
#### Return value
Explanation for return value.
A newline followed by a rule line (---) should always end each function section.
Here's a typical layout for a function taken from the array function documentation:
## Functions
### `arrayCompact()` <!-- index="Functions:Array functions" -->
#### Syntax
```JavaScript
arrayCompact(ary)
```
Returns a copy of array `ary` with all falsey elements removed.
#### Parameters
* `ary`
An array.
#### Return value
An array.
---
### `arrayFlatten()` <!-- index="Functions:Array functions" -->
#### Syntax
```JavaScript
arrayFlatten(ary)
```
Returns a copy of array `ary` with the contents of array elements added in place of that
array. The array elements are recursively processed in depth-first order as required to
remove all array elements. Unlike the array `flat()` method, `arrayFlatten(ary)` will
flatten all nested arrays regardless of depth.
#### Parameters
* `ary`
An array.
#### Return value
An array.
---
```