Coding guidelines

Parameters

Parameters will be divided into 3 broad categories, parentProps, required parameters and optional parameters.

Required parameters will not have default values, they must be provided as arguments every time the class is used.

Optional parameters may have default values, but they may also have no default value. No default value is preferred, and the class will intentionally handle the scenario where it is undefined. Some examples of correct default values for optional parameters include:

The parameter is a constrained list of possible values (ex. size: 'small' | 'medium' | 'large').
The parameter is of type boolean, in which case false is preferred to undefined.

We will take advantage of type checking to help make sure the classes are being used correctly. In the jsdocs, required parameters are defined as usual and optional parameters will be enclosed in brackets. Example:

* @param {AppProps} parentProps
* @param {object} params
* @param {number} params.requiredParameter
* @param {boolean} [params.optionalParameter]

This will make VSCode flag as an error any situation in which the class is being called without all required parameters.

Classes

When creating a class, the constructor will generally have 2 parameters: parentProps and an object called 'params' containing the rest of them. Some classes may not need parentProps, or a params object, or either of them; in those cases they are not added, which means some specific classes may instead have 1 or 0 parameters. Example of the typical class:

class Example {
  constructor(parentProps, {requiredParameter, optionalParameter = true, anotherOptionalParameter}) { }
}

When a class has a params object as parameter, but all of them are optional, the entire object must be given the default value of empty object. If at least one parameter is required, this default value is not included. Example:

constructor(parentProps, {optional1, optional2 = 'small'} = {})
constructor(parentProps, {required, optional})