首页
code-quality
tursodatabase/turso
通用正确性规则、Rust 模式、注释以及避免过度设计。编写代码时务必始终将这些因素考虑在内。
...展开全部关于代码质量
code-quality 是 Turso（Limbo）数据库项目所制定的简明编码规范参考文档，汇总了贡献者在编写代码时应当遵循的正确性规则、Rust 语言习惯以及相关注释与反过度设计指导。其核心理念是：这是一个用于生产环境的数据库，正确性至关重要，系统崩溃总比数据损坏更可接受，因此该文档明确了能够保障代码库安全的开发习惯。
该指南列出了正确性规则（禁止使用临时变通方案或快速hack，应频繁使用 assert 进行验证，面对可能威胁数据完整性的无效状态时应让程序崩溃，并需充分考虑边界情况），以及 Rust 语言模式（使非法状态无法被表示，采用穷尽式模式匹配，优先使用枚举而非字符串/哨兵值，尽量减少堆内存分配，编写对 CPU 友好的代码）。它还提供了具体的 if 语句处理建议——对于永远不可能被触发的分支，应使用 assert!、返回错误或使用 unreachable!，而非默默忽略它们；同时制定了注释规则，强调要记录原因而非仅描述内容，并禁止出现与 AI 对话相关的表述以及时间标记。此外，文档还提醒需仔细核对索引修改的顺序，确保其与 SQLite 的要求一致，以避免出现不一致问题；提及了相关的异步 I/O 模型技能要点；并列出了防止遗留死代码或向后兼容性 hack 的清理规则。
该文档主要面向 Turso/Limbo Rust 代码库的贡献者，同时也适用于任何希望拥有简明正确性检查清单的系统级 Rust 开发者。它纯属建议性文档——不包含任何脚本、命令、凭证或会产生副作用的内容，因此完全无害。
常见问题
核心理念是什么？
这是一个用于生产环境的数据库，正确性至关重要，因此系统崩溃总比数据损坏更可接受。相关规则旨在迫使程序在出现错误时明确报错，而非继续处于状态不明的状况。
如何处理那些永远不可能发生的分支？
不要默默忽略它们。应使用带有不变量说明的 assert!、返回错误，或使用 unreachable!——仅将普通的 if/else 用于两种分支都是预期路径的情况。
注释规则有哪些？
要记录原因而非仅描述内容，需对函数、结构体、枚举和变体进行文档说明，同时避免出现重复代码、引用 AI 对话内容，或包含“已添加”或“第一阶段”之类时间标记的注释。
它是否适用于 Turso 之外的项目？
该文档是为 Turso/Limbo Rust 代码库编写的，但其关于正确性及 Rust 语言习惯的指导原则对系统级 Rust 开发同样具有广泛适用性。
为何要强调索引修改的顺序？
因为插入、删除操作以及冲突解决操作的顺序必须与 SQLite 的要求保持一致；错误的顺序容易引发难以察觉的索引不一致问题。
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
Rust Patterns
- Make illegal states unrepresentable
- Exhaustive pattern matching
- Prefer enums over strings/sentinels
- Minimize heap allocations
- Write CPU-friendly code (microsecond = long time)
If-Statements
Wrong:
if condition { // happy path} else { // "shouldn't happen" - silently ignored}
Right:
// If only one branch should ever be hit:assert!(condition, "invariant violated: ...");// ORreturn Err(LimboError::InternalError("unexpected state".into()));// ORunreachable!("impossible state: ...");
Use if-statements only when both branches are expected paths.
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")
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
Index Mutations
When code involves index inserts, deletes, or conflict resolution, double-check the ordering against SQLite. Wrong ordering causes index inconsistencies. and easy to miss.
Ensure understanding of IO model
- Async IO model
Cleanup
- Delete unused code completely
- No backwards-compat hacks (renamed
_vars, re-exports,// removedcomments)
