# Engine-writing Guidelines

* **Never use `unsafe`**, unless you have already:
* tried every other possible solution;
* rewritten the universe from scratch;
* consulted with the rest of the team during a meeting;
* asked if it's possible to do without `unsafe` on the [Rust user forum](https://users.rust-lang.org/c/help/5) and the answer is no.

* **Never bypass the pre-commit hooks.**
* If you encounter an issue that is not possible to resolve, ask on Slack.

* **Always write meaningful documentation.**
* clippy will require you to document everything that is public, but don't write low-effort documentation comments.
* Describe behavior, not implementation. You shouldn't have to update a documentation comment when changing the implementation.

* **Never panic -- instead return `Result`**, unless:
* you are absolutely sure the code is written in a way that the panic can't happen;
* you provide a meaningful message in `.expect("...")`.

* **Always write tests.**
* Unit test everything.
* Integration test major components of the engine (i.e. scheduler, execution of systems).
* Write examples that show how to use your code.
* **When fixing a bug, always write a regression test before fixing it** to ensure both that it is fixed and it doesn't arise again.

* **Use the type system to encode information.**
* For example, don't take `i32` as a parameter to a function, create a [newtype](https://www.lurklurk.org/effective-rust/newtype.html) and call it `DelayInMilliseconds(i32)`.

* **Create issues for each `// todo(#123): `.**
* Whenever you find a part of the code that can be improved, or is incorrect, but is not your current task -- leave a todo-comment!
* So this doesn't get forgotten, create an issue on the project board.
* Include the issue # in the todo-comment!