Javascript code standards for GU

javascript-standards.md

Javascript code standards for GU

This document outlines best practices and standards for Javascript code written for GU projects. They are largely taken from the W3 Schools JavaScript Style Guide and the Wordpress Javascript Coding Standards.

Variables

• Variable names should begin with a letter and be written in camelCase.
• Variable names should be descriptive of the information they contain, even if it makes the variable a little long (but don't go overboard).
• Use const for all variables that will definitely not change.
• Use let for local variables inside a function or callback.
• Use var only if you need a more global variable.

Comments

• Each file should begin with a multi-line comment block, detailing the file's purpose.
  • Example:

  /**
   * BLOCK: Song List.
   * 
   * Custom block for displaying a list of songs.
   */
  

• Each function in a file should be preceded by a multi-line comment, explaining the purpose and/or usage of the function.
  • Example:

  /*
   * Function: sing()
   *
   * This function will sing a song to you.
   */
  

• Individual lines that require a bit of explanation should be preceded by a single-line comment.
  • Example:

  // If I go, there will be trouble. If I stay, it will be double.
  let trouble = (go()) ? trouble : trouble * 2;
  

Code indentation

• All code inside a block (i.e. function, loop, if statement, etc) should be indented.
• An indentation is 2 spaces. Not tabs. Don't @ me.

Spaces around operators

• There should be 1 space around all arithmetic and conditional operators (+, -, ==, +=), as well as commas.
• The only exception to this is the ! (not), because that just looks weird.
• There should be no space after a beginning parenthesis and before an end parenthesis.
  • Example: function sayHello(name) {
  • Example: if (name == 'The Doctor') {

Statements

• End simple statements with a semi-colon.
  • Example: const name = 'The Doctor';
• For blocks (functions, loops, if statements):

  • Put the opening bracket at the end of the first line.

  • Use one space before the opening bracket.

  • Put the closing bracket on a new line, without leading spaces.

    • Example:

    if (name == 'The Doctor') {
      console.log('Run!');
    }
    

Namespacing

Namespacing is not really a core feature of Javascript. It is something that is accomplished with code patterns. Namespacing here is done via the Module pattern.

• The top namespaced object should be declared using let.
• Functionality as part of a single namespace should be split into individual files.
• The namespaced object should always check to see if it already exists, since functionality is split up.
• Functions and variables can be added directly to the namespace, once it is declared.

Namespacing example

let guNamespace = guNamespace || {};

guNamespace.color = 'purple';

guNamespace.getColor = () => {
  return this.color;
}

References

• https://www.oreilly.com/library/view/learning-javascript-design/9781449334840/ch13s15.html

Modules

• Any reusable piece of functionality should be developed as an exportable module.
• Modules should be declared as part of a namespace.
• Module names should be saved in a file of the same name. So, if the module is named reuseMe, the file that contains that module should be named reuseMe.js.

Module example

let guNamespace = guNamespace || {};

guNamespace.reuseMe = () => {
  console.log('Hello world!');
}

export default guNamespace.reuseMe;

Custom Gutenberg blocks

• Custom Gutenberg blocks should be written as a series of modules that are called by the index.js file for that block. This means that the icons, deprecated object, edit() function, and save() function are all individual modules.
• Any core functions or React blocks that are used from WordPress libraries should be declared as const.