188 lines
3.5 KiB
Markdown
188 lines
3.5 KiB
Markdown
# Style Guide
|
|
|
|
- Generally, try to write TypeScript that is more like Erlang and
|
|
less like Javascript
|
|
|
|
- Code is read more often than it is written. So be kind to people
|
|
reading the code. Make it obvious and simple.
|
|
|
|
- All of these rules are fuzzy and there are times where it is good
|
|
or necessary to break them. You're an adult, use your best
|
|
judgment.
|
|
|
|
- It's OK to write code with a larger number of lines if the result
|
|
is code that is more readable.
|
|
|
|
- Don't try to be l33t. Boring code is best
|
|
|
|
- Don't sacrifice readability for "performance". It's far easier to
|
|
optimize inefficient/correct code than to correct
|
|
efficient/incorrect code.
|
|
|
|
- It should be simple. It should just work. And it should be obvious
|
|
to anyone reading the code why it works.
|
|
|
|
- Prefer `let` over `var` or `const`
|
|
|
|
- Avoid taking advantage of mutability. A recursive function is
|
|
usually better than a loop
|
|
|
|
```js
|
|
|
|
```
|
|
|
|
- Put your "this does stuff" code in a function called `main` and
|
|
then call it.
|
|
|
|
```js
|
|
// no
|
|
do_something();
|
|
do_something_else();
|
|
|
|
// yes
|
|
function main()
|
|
{
|
|
do_something();
|
|
do_something_else();
|
|
}
|
|
main();
|
|
```
|
|
|
|
- Every `if` should have an `else`
|
|
|
|
```js
|
|
// no
|
|
function foo(bar)
|
|
{
|
|
if (some_condition(bar))
|
|
{
|
|
return;
|
|
}
|
|
|
|
do_something();
|
|
do_something_else();
|
|
}
|
|
|
|
// yes
|
|
function foo(bar)
|
|
{
|
|
if (some_condition(bar))
|
|
{
|
|
return;
|
|
}
|
|
else
|
|
{
|
|
do_something();
|
|
do_something_else();
|
|
}
|
|
}
|
|
```
|
|
|
|
- Avoid hidden state like the plague (this means don't make objects;
|
|
use records instead). All of your ingredients should be declared
|
|
visually near where they are used.
|
|
|
|
This means no oopy jogger jizz, "stamps", etc
|
|
|
|
- Every function should have a unique name so that someone unfamiliar
|
|
with the codebase can `grep -rn function_name` and find it
|
|
immediately
|
|
|
|
- Do not use the ternary operator `returnValue = condition ? ifTrue :
|
|
else`. It's just obnoxious (most of the time)
|
|
|
|
- In general, avoid binary operators. If you must use them, don't be
|
|
niggardly with parentheses. Disambiguating infix precedence is a
|
|
nightmare.
|
|
|
|
- Inequalities should follow the left-to-right orientation of the number line
|
|
|
|
```js
|
|
// cringe
|
|
let x = y > z;
|
|
|
|
// based
|
|
let x = z < y;
|
|
```
|
|
|
|
- Don't assume the person reading the code is a domain expert in
|
|
JavaScript. Avoid using weird JS syntax or runtime quirks.
|
|
|
|
- If you must, put weird things in variables or functions that have a
|
|
semantic name
|
|
|
|
```js
|
|
// wat
|
|
if (window == window.parent)
|
|
{
|
|
...
|
|
}
|
|
else
|
|
{
|
|
...
|
|
}
|
|
|
|
// obvious
|
|
let we_are_executing_this_in_a_browser = (window == window.parent);
|
|
if (we_are_executing_this_in_a_browser)
|
|
{
|
|
...
|
|
}
|
|
else
|
|
{
|
|
...
|
|
}
|
|
```
|
|
|
|
- Names should be in `snake_case`
|
|
|
|
- Indentation is 4 spaces
|
|
|
|
- Align things that deserve to be aligned
|
|
|
|
```js
|
|
function foo(bar : x,
|
|
baz : y,
|
|
quux : z)
|
|
{
|
|
}
|
|
```
|
|
|
|
- Open and close braces should align vertically so someone reading
|
|
can just scan to find the other delimiter.
|
|
|
|
```js
|
|
// yuck
|
|
if (condition) {
|
|
...
|
|
} else if (some_other_condition) {
|
|
...
|
|
} else {
|
|
...
|
|
}
|
|
|
|
// nice
|
|
// it's easy for a reader to visually match the open/close braces,
|
|
// and then to look at the line immediately above the opening brace
|
|
// to see what the code block corresponds to
|
|
if (condition)
|
|
{
|
|
...
|
|
}
|
|
else if (some_other_condition)
|
|
{
|
|
...
|
|
}
|
|
else
|
|
{
|
|
...
|
|
}
|
|
```
|
|
|
|
- Avoid sawtoothy code with a lot of nesting. If you're writing
|
|
sawtoothy code, you should probably factor it into many simple
|
|
functions.
|
|
|
|
- It is much easier to understand 20 simple functions than 1
|
|
complicated function.
|