首頁
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)
