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")