home / skills / tursodatabase / turso / code-quality

code-quality skill

safe

This skill enforces robust Rust code quality by promoting correctness, exhaustive patterns, and clear documentation to prevent crashes and bugs.

npx playbooks add skill tursodatabase/turso --skill code-quality

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.0 KB

---
name: code-quality
description: General Correctness rules, Rust patterns, comments, avoiding over-engineering. When writing code always take these into account
---
# Code Quality Guide

## Core Principle

Production database. Correctness paramount. Crash > corrupt.

## Correctness Rules

1. **No workarounds or quick hacks.** Handle all errors, check invariants
2. **Assert often.** Never silently fail or swallow edge cases
3. **Crash on invalid state** if it risks data integrity. Don't continue in undefined state
4. **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:
```rust
if condition {
    // happy path
} else {
    // "shouldn't happen" - silently ignored
}
```

Right:
```rust
// 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

## Ensure understanding of IO model

- [Async IO model](../async-io-model/SKILL.md)

## Cleanup

- Delete unused code completely
- No backwards-compat hacks (renamed `_vars`, re-exports, `// removed` comments)

Overview

This skill captures practical code-quality guidelines for writing correct, efficient Rust for an embedded SQL database. It emphasizes correctness, clear invariants, and pragmatic engineering decisions to avoid data corruption or crashes. The guidance covers Rust patterns, conditional handling, commenting, and when to avoid over-engineering.

How this skill works

It inspects code choices and suggests fixes that preserve correctness and performance in a database context. The skill flags unsafe or silent failure patterns, recommends making illegal states unrepresentable, and enforces explicit error handling or assertions. It also guides comment use and when to avoid premature abstractions or unnecessary changes.

When to use it

When implementing or changing core database logic where correctness matters.
When adding error handling, control flow, or state transitions in Rust.
When reviewing pull requests for safety, performance, and maintainability.
When deciding whether to introduce new abstractions or refactor similar code.
When documenting non-obvious design rationales or invariants.

Best practices

Crash rather than continue in an invalid state that could risk data integrity.
Make illegal states unrepresentable using types and exhaustive enums.
Assert invariants explicitly and handle every error path; never silently ignore failures.
Prefer CPU-friendly, low-allocation approaches suitable for in-process databases.
Document WHY a decision exists; avoid comments that restate code or include temporal notes.
Delete unused code and avoid backwards-compatibility hacks hidden in names or comments.

Example use cases

Replace a silent else branch with an explicit assert!, unreachable!, or a returned error.
Convert string-based state sentinels into an enum with exhaustive matching.
Reject a proposed refactor that introduces a heavyweight abstraction for three similar lines.
Add a brief comment explaining a non-obvious concurrency invariant or IO model assumption.
Refactor hotspot code to reduce heap allocations and improve microsecond-level latency.

FAQ

When should I crash instead of returning an error?

Crash if continuing risks data corruption or leaves the system in an undefined state; use explicit assertions or unreachable! for violated invariants. For recoverable user errors, return concrete errors.

How much commenting is enough?

Focus comments on why a choice exists, not what the code does. Document invariants, trade-offs, and any non-obvious interactions with the IO model.