代码约定
j8 的代码风格有一套明确的规矩,PR 要遵守。
结构
- 子模块私有
mod,crate 根pub use平铺导出,⛔pub mod;可见性靠私有mod,只写pub。 - 依赖方向:各层只依赖
j8framework;j8framework不依赖任何层;j8bytecode是根。 dune/与samples/*各自成包(自带空[workspace]),按版本依赖发布的j8,⛔ 路径依赖。新接口还没发版时, 本地用命令行--config打[patch.crates-io],⛔ 把 patch 或带 patch 生成的锁文件提交进仓库。
Rust
- ⛔
static与'static生命周期(枚举里的&'static str名字除外);不留全局 / 静态存储。后台任务用Task<'t>借用调用方数据。 - 字符串反序列化后立即转枚举,⛔ 拿字符串做判断。
- 转换走
From/TryFrom/Into,⛔ 手写to_xxx式转换函数(需要额外参数时除外)。 - 函数尽量是某个类型的方法:参数里只有一个可变类型就挂给它,有大结构体就挂给大结构体。
- 尽量用引用、借用、切片。
- 系数、阈值、字段编码一律具名
const,⛔ 裸数字。 - 代码里不写出处(量测时间、机器、提交号):这些进提交说明。
- 能用宏与生成器减少代码就用:字节码表从 V8 头文件生成,堆结构体用
#[heap],绑定用#[j8::class]。 - 源码里不写注释;文档放在 README、指南和本书里。
堆
- 回收会搬对象:⛔ 把
Gc或对象地址存进不被追踪的地方。 - 值进堆之后才能写它的槽。
- 只做停顿式回收,⛔
mark_concurrently。 - 无锁结构手写在 j8lockfree,⛔ crossbeam。
详见堆与 GC。
测试
- 单元测试只钉确定的、有真实数据背书的事实,不确定的不写(否则钉住的全是错误的特征)。
- 每次只跑一个单元测试,
timeout 15。 - test262 基线零回归。
文档
- 英文为主:仓库和每个发布的子包都有
README.md(英文,缺省)+README.zh-CN.md译本,互相链接。 - 本书以英文为主、附中文译本,改一种语言时请同步另一种。
提交
- j8 在 GitHub(0x00-Community/j8)上走分支 + PR,main 受保护;PR 合并后分支自动删除。