Vanillae/sidekick/scratch/STYLE_GUIDE.md

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.