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

Put your "this does stuff" code in a function called main and then call it.

// no
do_something();
do_something_else();

// yes
function main()
{
    do_something();
    do_something_else();
}
main();

Every if should have an else

// 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

// 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

// 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

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.

// 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.

3.5 KiB Raw Blame History

Style Guide

3.5 KiB

Raw Blame History