Establish code design/format guidelines about akita

[sharon-wang]

We've decided that multi-line comment format, i.e.

/*
 *
 */

is reserved for documentation outside of functions/code.

// will be used for single line comments only, such as in-line documentation with code.

---

All comments should use sentence case (i.e. start with a capital), but only multi-line comments should include periods. Single line comments should not end with a period.

Multi-line example

/**
 * Retrieve the favicon path.
 * 
 * @return {String} The absolute or relative path from the site origin to the favicon.
 */

Single line example

// Default favicon path is at the root of the origin

[vezwork]

We've decided that early returns in functions are preferred over returning once at the end of a function, i.e.
✅ PREFERRED:

function example(input) {
  if (input !== null) {
    return true;
  }
  return false;
}

❌ NOT-PREFERRED:

function example(input) {
  const result = false;
  if (input !== null) {
    result = true;
  }
  return result;
}

Justification: early returns make it easier to understand a code-path of a function without having to read the entire function. They also make it so that you do not have to think about and keep track of function-scoped variables while reading the function.

Note that there are cases where it could be better to not early return, for example if you have to cleanup resources before returning, it may be better to have that cleanup code once at the end of the function before you return.

[vezwork]

It would be good to have html style opinions. The formatting is quite strange and not especially readable right now. (Sharon thinks so too).