-
-
Notifications
You must be signed in to change notification settings - Fork 248
Style Guide
Most functions that deal with components are retrieving access to them via getComponent
in the beginning of the function definition:
const halfMyComponentValue = (entity: Entity) => {
const myComponent = getComponent(entity, MyComponent)
myComponent.value /= 2
}
const quarterMyComponentValue = (entity: Entity) => {
const myComponent = getComponent(entity, MyComponent)
myComponent.value /= 4
}
However, most of these functions are being used in a context where the components have already been retrieved, or will need retrieved again in a following function, thus creating a lot of redundant getComponent
calls:
const MySystem = (world) => {
const entities = query(world)
for (const entity of entities) {
const myComponent = getComponent(entity, MyComponent)
myComponent.value += 100
halfMyComponentValue(entity)
quarterMyComponentValue(entity)
}
}
This potentially may have a significant impact on performance by inducing more lookups than are necessary. Instead, getComponent
should be called once per entity iteration in a system, the reference of which can then be passed into respective function calls.
const halfMyComponentValue = (myComponent) => {
myComponent.value /= 2
}
const quarterMyComponentValue = (myComponent) => {
myComponent.value /= 4
}
const MySystem = (world) => {
const entities = query(world)
for (const entity of entities) {
const myComponent = getComponent(entity, MyComponent)
myComponent.value += 100
halfMyComponentValue(myComponent)
quarterMyComponentValue(myComponent)
}
}
In this example, the number of lookups is reduced 3 * entities.length
times. This also makes the functions more referentially transparent.
Most functions in the codebase do not exhibit referential transparency. This can considerably enhance the readability of code, making it easier to work with, especially those who are new to the codebase.
In all cases. it is best to write lots of small functions, rather than large functions or classes. This allows us to easily create test cases for each function. These functions can then be overridden and extended by projects to enable easy modifications to the base functionality. The functional paradigm also enables a data-oriented approach.
Functions should not rely on external state where possible, such as mutating variables outside of the function's scope (see Pure vs Impure Functions). The exception is when a function's purpose is to mutate state, such as a FLUX pattern receiver, a database mutation, or ECS interaction.
Functions should have clear and readable names, to aid ease of understanding. It is perfectly fine for these to be verbose, the module export can have shortened names if they are unreasonably long.
// CustomMathUtil.ts
// modules files must be named identitcally to their module, while lone function files must be named identically to the function they export
const addOne = (i: number) => {
return i++
}
// functions must be camelCase
const subtractOne = (i: number) => {
return i--
}
// modules must be CapitalCase
export const CustomMathUtil = {
addOne,
subOne
}
When importing, it is important not to deconstruct these modules outside of the scope they are being used in, as the references will be kept, and if they have since been overridden, there will be a mismatch in functionality.
Bad
import { CustomMathUtil } from './CustomMathUtil'
const { addOne } = CustomMathUtil
function addTwo (number) {
return addOne(addOne(number))
}
Good
import { CustomMathUtil } from './CustomMathUtil'
function addTwo (number) {
const { addOne } = CustomMathUtil
return addOne(addOne(number))
}
To run all the unit & integration tests across the entire monorepo, use npm run test
in the root folder. To run
Individual tests can be run by navigating to the package the specific test is running in (such as cd packages/engine
) and running npm run test -- --grep describeHookLabel
where 'describeHookLabel' is the label of a describe hook in a specific test file.
The goal with testing to is to provide a variety of input states to a function, and test that a variety of output states are as expected. We define 3 types of tests.
These test individual pieces of functionality, such as isolated functions. Examples of some well-written unit tests can be found here and here
All global state (such as Engine.userId) must be reset before and after as to not affect the tests. This will soon be refactored to not be an issue.
An example of the styling for writing tests can be found below. It is important to respect the gap lines as to ensure readable code.
import assert from 'assert'
import { CustomMathUtil } from './CustomMathUtil'
describe('CustomMathUtil', () => {
describe('addOne', () => {
// first test case
it('should add one', () => {
const result = CustomMathUtil.addOne(1)
assert.equal(result, 2)
})
// second test case
it('should return NaN to non-number', () => {
const result = CustomMathUtil.addOne(undefined!)
assert.equal(result, NaN)
})
})
})