Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

代码约定

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 合并后分支自动删除。