reorganizing because zx needs to feel special

sidekick/scratch/STYLE_GUIDE.md

@@ -0,0 +1,187 @@
+# 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.