---
# System prepended metadata

title: Engine-writing Guidelines

---

# 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!

