Code conventions
j8 has explicit code rules; pull requests follow them.
Structure
- Private submodules (
mod), flattened bypub useat the crate root, ⛔pub mod; visibility comes from private modules, and items are plainpub. - Dependency direction: every layer depends only on
j8framework;j8frameworkdepends on no layer;j8bytecodeis the root. dune/andsamples/*are packages of their own (with an empty[workspace]) depending on the publishedj8by version, ⛔ path dependencies. When a new API isn’t published yet, patch locally with--configon the command line ([patch.crates-io]), ⛔ committing the patch or a lock file generated with it.
Rust
- ⛔
staticand the'staticlifetime (except&'static strnames in enums); no global or static storage. Background tasks borrow the caller’s data throughTask<'t>. - Strings are turned into enums right after deserializing, ⛔ deciding on strings.
- Conversions use
From/TryFrom/Into, ⛔ hand-writtento_xxxconversions (unless extra arguments are needed). - Functions are methods of a type wherever possible: of the one mutable type among the parameters, or of the big struct.
- Prefer references, borrows and slices.
- Coefficients, thresholds and field encodings are named
consts, ⛔ bare numbers. - No provenance in code (measurement dates, machines, commit ids): that goes in commit messages.
- Reduce code with macros and generators: the bytecode tables come from V8’s headers, heap structs use
#[heap], bindings use#[j8::class]. - Source code carries no comments; documentation lives in the READMEs, the guides and this book.
The heap
- Collection moves objects: ⛔ storing a
Gcor an object address where it isn’t traced. - Write a value’s slots only once it is on the heap.
- Stop-the-world collection only, ⛔
mark_concurrently. - Lock-free structures are hand-written in j8lockfree, ⛔ crossbeam.
See Heap and GC.
Tests
- Unit tests pin only certain facts backed by real data; nothing uncertain (otherwise they pin wrong behavior).
- One unit test at a time, under
timeout 15. - Zero test262 regressions.
Documentation
- English first: the repository and every published sub-package have a
README.md(English, the default) and aREADME.zh-CN.mdtranslation, linked to each other. - This book is English with a Chinese translation; change both together.
Commits
- j8 lives on GitHub (0x00-Community/j8): branches and pull requests, main is protected, and merged branches are deleted automatically.