Coding Style Conventions

Placing a wiki here to document the code style conventions that we have agreed upon moving forward.

Interface placement

Interfaces should be placed at the top of a module, preferably in alpha order in case of collisions.

Getters that return arrays currently just return the array directly, rather than a shallow copy (from slice()). We think this way of doing things is easier to reason about, but it might be worth changing later on.

Members / Functions that are publicly exposed to the user (essentially anything with a public modifier) should not start with an underscore "_", whereas members/functions that are not publicly exposed should start with an underscore "_". This is to make more clear to a Javascript consumer that underscored members should not be touched and if they are, it's an error on their or our end.

Refers to casting an object to be of type any so that we can have access to private members/functions.
In general, if something can be casted into some concrete type, please do so.
In tests, it is mainly ok to use this method to test/replace underlying functionality. Tend to not avoid this.
In source code, use this method extremely sparingly. By investing in anycasting, we are disabling our usage of Typescript's core strengths.

Stringy enums should be declared as exported vars in an exported module. For example,

export module Country {
  export var USA = "United States of America";
  export var CA = "Canada";
}

Boolean parameters should only be used in places where the method name makes it perfectly clear what the value of the boolean means:

Object.enabled(true)

is fine.

new XYPlot(xscale, yscale, false)

is not legible. The behavior of the code cannot be reasonably inferred from context.

Instead prefer

new XYPlot(xscale, yscale, "horizontal")

HACKHACKs by their nature should be used sparingly. In cases where they are forced to be used, they should be in the style:

// HACKHACK: <Issue number or URL> <Brief explanation>

The issue number or URL is important since it tells a future developer that a HACKHACK can be removed if the attached identifier is later marked as solved.
- Issue numbers can only be used for Github Plottable issues.
- URLs have a neat usage in Visual Studio Code since there is a feature to open links through the IDE.
The brief explanation is important since it tells a future developer why the HACKHACK needs to exist. It also may tell the developer enough information for them to remove the HACKHACK themselves if they can think up a way.