code-quality

代码质量指南

核心原则

生产数据库。正确性至关重要。崩溃胜过数据损坏。

正确性规则

1. 不要使用变通方案或临时凑合的技巧。 处理所有错误，检查不变量
2. 经常断言。 绝不静默失败或忽略边界情况
3. 如果无效状态可能危及数据完整性，就应当崩溃。 不要在未定义状态下继续运行
4. 考虑边界情况。 时间足够长，所有可能发生的错误都会发生

Rust 模式

• 让非法状态无法表示
• 使用穷尽式模式匹配
• 优先使用枚举，而非字符串或哨兵值
• 尽量减少堆分配
• 编写对 CPU 友好的代码（微秒也很长）

If 语句

错误：

if condition {
    // happy path
} else {
    // "shouldn't happen" - silently ignored
}

正确：

// If only one branch should ever be hit:
assert!(condition, "invariant violated: ...");
// OR
return Err(LimboError::InternalError("unexpected state".into()));
// OR
unreachable!("impossible state: ...");

仅当两个分支都是预期路径时才使用 if 语句。

注释

• 不要添加代码注释，Rust SAFETY 注释除外。

避免过度设计

• 只做直接要求或明确必要的更改
• 不要添加超出要求的功能
• 不要为未更改的代码添加文档字符串或注释
• 不要为不可能发生的情况添加错误处理
• 不要为一次性操作创建抽象
• 三行相似代码胜过过早抽象

索引变更

涉及索引插入、删除或冲突解决时，请对照 SQLite 仔细核查操作顺序。顺序错误会导致索引不一致，而且很容易被忽略。

确保理解 IO 模型

• 异步 IO 模型

清理

• 完全删除未使用的代码
• 不要使用向后兼容的变通方案（重命名的 _vars、重新导出、// removed 注释）

单次使用的辅助函数

如果辅助函数仅在某个用例中有意义，就将其移入调用该函数的函数中：

fn do_something() {
    
    something_specific();

    fn something_specific() {
    }
}