code-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Quality Guide

代码质量指南

Core Principle

核心原则

Production database. Correctness paramount. Crash > corrupt.

生产环境数据库，正确性至关重要。程序崩溃优于数据损坏。

Correctness Rules

正确性规则

No workarounds or quick hacks. Handle all errors, check invariants
Assert often. Never silently fail or swallow edge cases
Crash on invalid state if it risks data integrity. Don't continue in undefined state
Consider edge cases. On long enough timeline, all possible bugs will happen

禁止临时解决方案或快速补丁。 处理所有错误，检查不变量
频繁使用断言。 绝不静默失败或忽略边缘情况
若存在数据完整性风险，在无效状态时直接崩溃。不要在未定义状态下继续运行
考虑边缘情况。 从长远来看，所有可能出现的bug终会发生

Rust Patterns

Rust编程模式

Make illegal states unrepresentable
Exhaustive pattern matching
Prefer enums over strings/sentinels
Minimize heap allocations
Write CPU-friendly code (microsecond = long time)

让非法状态无法被表示
穷举模式匹配
优先使用枚举而非字符串/标记值
最小化堆内存分配
编写CPU友好型代码（微秒级时长已算较长）

If-Statements

条件语句

Wrong:

rust

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

Right:

rust

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

Use if-statements only when both branches are expected paths.

错误示例：

rust

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

正确示例：

rust

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

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

Comments

代码注释

Do:

Document WHY, not what
Document functions, structs, enums, variants
Focus on why something is necessary

Don't:

Comments that repeat code
References to AI conversations ("This test should trigger the bug")
Temporal markers ("added", "existing code", "Phase 1")

建议做法：

注释说明原因，而非内容
为函数、结构体、枚举、枚举变体添加文档注释
重点说明某项实现的必要性

禁止做法：

重复代码内容的注释
引用AI对话的注释（如“这个测试应该触发该bug”）
带有时间标记的注释（如“已添加”、“现有代码”、“第一阶段”）

Avoid Over-Engineering

避免过度工程化

Only changes directly requested or clearly necessary
Don't add features beyond what's asked
Don't add docstrings/comments to unchanged code
Don't add error handling for impossible scenarios
Don't create abstractions for one-time operations
Three similar lines > premature abstraction

仅进行直接要求或明确必要的修改
不要添加超出需求的功能
不要为未修改的代码添加文档注释
不要为不可能出现的场景添加错误处理
不要为一次性操作创建抽象层
三行相似代码 > 过早抽象

Ensure understanding of IO model

确保理解IO模型

Async IO model

异步IO模型

Cleanup

清理工作

Delete unused code completely
No backwards-compat hacks (renamed
```
_vars
```
, re-exports,
```
// removed
```
comments)

彻底删除未使用的代码
不要保留向后兼容的补丁（如重命名的
```
_vars
```
、重新导出项、
```
// removed
```
注释）