Home

Skill

Documentation

code-quality

tursodatabase/turso

General Correctness rules, Rust patterns, comments, avoiding over-engineering. When writing code always take these into account

...Expand all

Updated time August 22, 2026

# documentation # database # code-quality # rust # DocumentationDatabase Management # code-conventions

About code-quality

code-quality is a concise coding-convention reference for the Turso (Limbo) database project, capturing the correctness rules, Rust idioms, and commenting and anti-over-engineering guidance that contributors should apply whenever writing code. Its guiding principle is that this is a production database where correctness is paramount and a crash is preferable to data corruption, so it codifies the habits that keep the codebase safe.

The guide lays out correctness rules (no workarounds or quick hacks, assert often, crash on invalid state that risks data integrity, consider edge cases) and Rust patterns (make illegal states unrepresentable, exhaustive pattern matching, prefer enums over strings/sentinels, minimize heap allocations, write CPU-friendly code). It gives concrete if-statement guidance — use assert!, return an error, or unreachable! for branches that should never be hit rather than silently ignoring them — and commenting rules that favor documenting why over what while banning AI-conversation references and temporal markers. It also warns to double-check index-mutation ordering against SQLite to avoid inconsistencies, points to a related async I/O model skill, and lists cleanup rules against leaving dead code or backwards-compat hacks.

It targets contributors to the Turso/Limbo Rust codebase and, more broadly, anyone writing systems-level Rust who wants a compact correctness checklist. It is purely advisory documentation — no scripts, commands, credentials, or side effects — making it entirely benign.

FAQ

What is the core principle?

This is a production database where correctness is paramount, so a crash is preferable to data corruption. The rules push you to fail loudly rather than continue in an undefined state.

How should I handle branches that should never happen?

Don't silently ignore them. Use assert! with an invariant message, return an error, or unreachable! — reserve plain if/else for cases where both branches are expected paths.

What are the commenting rules?

Document why rather than what, document functions/structs/enums/variants, and avoid comments that repeat code, reference AI conversations, or contain temporal markers like 'added' or 'Phase 1'.

Does it apply beyond Turso?

It is written for the Turso/Limbo Rust codebase, but its correctness and Rust-idiom guidance is broadly useful for systems-level Rust work.

Why does it call out index mutations?

Because insert, delete, and conflict-resolution ordering must match SQLite; wrong ordering causes index inconsistencies that are easy to miss.

View on GitHub

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.