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

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: ..."); // OR return Err(LimboError::InternalError("unexpected state".into())); // OR unreachable!("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, // removed comments)