Rust Coding Style

Apply these rules when writing or reviewing Rust code. Keep decisions consistent and terse.

Examples

• "Pick an error strategy for this new Rust binary."
• "Decide API shape and module layout for this Rust crate."

Guidelines

Control flow and logging

• Never use a fallback branch unless explicitly instructed.
• Never ignore a match branch unless explicitly instructed. For unhandled events, use tracing with at least warn! and include a {:?} debug of the event.

Placeholders and stubs

• When placing placeholders or stubs, use todo!(). Do not create empty files.

Language

• Do not use the word "plumbing".

Error handling

• New app: prefer thiserror.
• IO-only code: prefer std::io::Result.
• Existing eyre/anyhow: stick with it.
• New library: prefer thiserror.
• Within a codebase, keep the existing error crate unless you have a strong reason to change.

API design

• Public API: return Result<T, E> and avoid panics.
• Prefer newtypes over type aliases for invariants.
• Use impl Trait in return position for iterator APIs.
• For many optional params: use a builder.
• Config load API: prefer free function fn load(path: impl AsRef<Path>) -> Result<Config, Error>.
• Iterator exposure: prefer fn iter(&self) -> impl Iterator<Item = &Item>.
• Optional config fields: use #[serde(default)] and concrete fields; avoid Option<T> in the struct.
• Validation on construction: prefer builder with build() -> Result<Self, Error>.
• Never implement From/TryFrom for wrapper newtypes. Unless they are Error types.

Code structure

• Small module: use mod.rs; large module: use mod/ with mod.rs.
• Default to feature-based grouping in Rust (e.g., src/foo/mod.rs).
• Only use layer-based grouping for legacy or mandated layouts.
• Use mod.rs to curate public APIs rather than re-exporting entire trees, unless the mods are private.

Naming

• Use singular for a thing/type, plural for a collection/module.
• File naming: client.rs for a single client type, clients/ for a collection.

API style: free functions vs structs

• Prefer struct + impl when there is shared state, configuration, or invariants.
• Prefer struct if a function has only the struct as parameter, and tie closely to the struct's purpose.
• Prefer free functions for stateless operations.
• Avoid OOP-style class hierarchies; use traits for behavior and composition.
• Use a builder when construction has multiple stages or invariant checks.

Ownership and lifetimes

• Prefer owning types in public APIs; borrow internally where possible.
• Avoid exposing explicit lifetimes unless they simplify the API.

Async boundaries

• Keep async at the edges; core logic stays sync when possible.
• Prefer explicit async fn in public APIs; avoid boxed futures unless needed.
• Use tokio only when async IO or concurrency pays for the complexity.

Performance

• Prefer cargo criterion over cargo bench.
• Use cargo flamegraph for CPU hotspots.
• Use perf + flamegraph for low-level profiling on Linux.
• Use samply for sampling + flamegraphs on macOS/Linux.
• Use tokio-console for async task/latency insight.
• Use cargo llvm-lines for codegen size hotspots.
• Use cargo bloat for binary size breakdown.

Testing

• In-file unit tests for local behavior and edge cases.
• tests/ for integration tests across modules/crates.
• Shell integration tests for CLI workflows.
• Smoke tests for minimal end-to-end coverage.
• Mock tests when dependencies are expensive or flaky.
• Fuzz tests for parsers, serializers, and input handling.
• Use Podman Compose for containerized integration tests.