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,// removedcomments)
