existential-birds/beagle / plugins/beagle-rust/skills/rust-best-practices
rust-best-practices
VerifiedDevelopment guidance for writing idiomatic Rust. Use when: (1) writing new Rust functions or modules, (2) choosing between borrowing, cloning, or ownership patterns, (3) implementing error handling with Result types, (4) optimizing Rust code for performance, (5) configuring clippy and linting for a project, (6) deciding between static and dynamic dispatch, (7) writing documentation or doc tests.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.2 KB |
| references/api-design.md | markdown | 15.3 KB |
| references/clippy-config.md | markdown | 4.0 KB |
| references/coding-idioms.md | markdown | 13.7 KB |
| references/documentation.md | markdown | 5.5 KB |
| references/ecosystem-patterns.md | markdown | 5.5 KB |
| references/generics-dispatch.md | markdown | 9.9 KB |
| references/performance.md | markdown | 10.5 KB |
| references/pointer-types.md | markdown | 5.1 KB |
| references/type-state-pattern.md | markdown | 3.5 KB |
references/api-design.md
View on GitHub# API Design
## Four Principles
Every Rust interface should be **unsurprising** (follow naming conventions and standard trait expectations), **flexible** (avoid unnecessary restrictions on callers), **obvious** (use types and docs to prevent misuse), and **constrained** (expose only what you intend to support long-term).
## Naming Conventions
Follow the Rust API Guidelines. Reuse well-known names so users can rely on intuition:
- `iter` takes `&self` and returns an iterator
- `into_inner` takes `self` and returns a wrapped value
- `SomethingError` implements `std::error::Error`
Avoid using familiar names for unfamiliar behavior -- if `iter` takes `self`, users will write bugs.
## Standard Trait Implementations
Eagerly implement standard traits even if you don't need them yet. Users cannot implement foreign traits on your types due to coherence rules.
**Priority order:**
1. `Debug` -- nearly every type should have it
2. `Send`, `Sync` -- document if intentionally missing
3. `Clone`, `Default` -- expected for most types
4. `PartialEq`, `Hash` -- needed for collections and assertions
5. `Serialize`/`Deserialize` -- behind a `serde` feature flag
Avoid deriving `Copy` by default. It changes move semantics, and removing it later is a breaking change.
## Making Invalid States Unrepresentable
Use the type system to prevent misuse at compile time rather than panicking at runtime.
```rust
// BAD -- runtime check, caller can pass wrong combination
fn launch(rocket: &mut Rocket, is_fueled: bool, is_on_ground: bool) {
assert!(is_fueled && is_on_ground);
}
// GOOD -- invalid calls are compile errors
struct Grounded;
struct Launched;
struct Rocket<Stage = Grounded> {
stage: std::marker::PhantomData<Stage>,
}
impl Rocket<Grounded> {
fn launch(self) -> Rocket<Launched> { /* ... */ }
}
```
Combine related booleans into enums. If a pointer is only valid when a flag is true, use an `Option` or a single enum with the data inside the relevant variant.
## Builder Pattern
Use when constructing types with many optional fields or when required fields must be validated before use.
```rust
pub struct ServerConfig { /* private fields */ }
pub struct ServerConfigBuilder {
host: String,
port: Option<u16>,
tls: Option<TlsConfig>,
}
impl ServerConfigBuilder {
pub fn new(host: impl Into<String>) -> Self {
Self { host: host.into(), port: None, tls: None }
}
pub fn port(mut self, port: u16) -> Self {
self.port = Some(port);
self
}
pub fn build(self) -> Result<ServerConfig, ConfigError> {
// validate and construct
}
}
```
For builders with required stages, combine with type-state pattern (see [type-state-pattern.md](type-state-pattern.md)).
## `impl Trait` in Argument vs Return Position
**Argument position** (`fn foo(x: impl Read)`) -- syntactic sugar for generics. Caller chooses the concrete type. Monomorphized, so each type gets its own copy.
**Return position** (`fn foo() -> impl Read`) -- caller does not choose the type. Useful for hiding complex return types (iterators, closures, futures). In edition 2024, captures all in-scope lifetimes by default.
```rust
// Argument position: caller picks the type
fn process(input: impl AsRef<str>) { /* ... */ }
// Return position: hides the concrete iterator type
fn even_squares(nums: &[i32]) -> impl Iterator<Item = i32> + '_ {
nums.iter().filter(|n| *n % 2 == 0).map(|n| n * n)
}
```
Prefer generics over `impl Trait` in arguments when the same type parameter is referenced multiple times or when the caller needs turbofish syntax.
## Sealed Traits
Prevent external crates from implementing your trait while still allowing them to use it. Useful for derived/blanket traits and restricting type parameters.
```rust
pub trait Stage: sealed::Sealed { /* ... */ }
mod sealed {
pub trait Sealed {}
impl Sealed for super::Grounded {}
impl Sealed for super::Launched {}
}
```
Document that the trait is sealed so users don't waste time trying to implement it.
## Newtype Pattern
Wrap a type to give it distinct semantics or work around the orphan rule.
```rust
// Semantic distinctness
struct Meters(f64);
struct Seconds(f64);
// Orphan rule workaround -- implement foreign trait for foreign type
struct PrettyVec<T>(Vec<T>);
impl<T: Display> Display for PrettyVec<T> { /* ... */ }
```
Use `Deref` to forward method calls to the inner type when the wrapper is transparent.
## Non-Exhaustive for Forward Compatibility
Prevent downstream code from constructing your types directly or matching exhaustively, so you can add fields/variants without a breaking change.
```rust
#[non_exhaustive]
pub enum Error {
NotFound,
PermissionDenied,
}
#[non_exhaustive]
pub struct Config {
pub timeout_ms: u64,
}
```
Use when the type is likely to gain new variants or fields. Avoid on stable types where exhaustive matching is valuable to callers.
## Blanket Implementations
Provide blanket impls for references when your trait has only `&self` methods:
```rust
impl<T: MyTrait> MyTrait for &T { /* forward calls */ }
impl<T: MyTrait> MyTrait for Box<T> { /* forward calls */ }
```
This lets `fn foo(x: impl MyTrait)` accept both owned values and references without surprises. Adding a blanket impl later is a breaking change due to coherence, so plan early.
## SemVer Implications
**Breaking changes** (require major version bump):
- Removing or renaming public items
- Adding fields to a non-`#[non_exhaustive]` struct
- Removing a trait implementation
- Adding a blanket trait implementation
- Making a trait no longer object-safe
- Changing auto-trait implementations (Send, Sync)
- Bumping a major version of a re-exported dependency
**Non-breaking changes:**
- Adding new public items
- Adding a trait method with a default implementation
- Implementing a trait for a new type
- Relaxing trait bounds on existing functions
Use `#[non_exhaustive]` on types you expect to evolve, seal traits you need to extend, and wrap re-exported foreign types in newtypes.
## Hidden Contracts
Some breaking changes do not show up in your signatures. The review-side companion in [../../rust-code-review/references/interface-design.md](../../rust-code-review/references/interface-design.md) catches these in diffs; on the development side, design around them up front.
**Re-exported foreign types.** `pub use serde::Serialize;` (or returning `serde_json::Value` from a public function) silently makes serde's major version part of your API contract. When serde bumps 1.x to 2.x, downstream code that mixes your crate with `serde 1.x` sees `serde1::Value` and `serde2::Value` as different types. Three defenses:
- Don't re-export. Keep foreign types out of your public surface.
- Wrap the foreign type in a newtype and expose only the methods you commit to.
- Return `impl Trait` with a minimal bound (`impl Iterator<Item = T>` rather than `itercrate::Empty<T>`) so the concrete foreign type is invisible.
**Auto-trait propagation.** `Send`, `Sync`, `Unpin`, `UnwindSafe` are inferred by the compiler from a type's contents and propagated through `-> impl Trait` and async fn bodies. A function whose body holds an `Rc<...>` across an `.await` silently downgrades its returned future to `!Send`, and downstream code that `tokio::spawn`s it stops compiling. The auto-trait status is part of your contract even though it appears nowhere in the signature.
To lock the contract, name it explicitly on the return type:
```rust
pub fn run(&self) -> impl Future<Output = ()> + Send + Sync + 'static {
async move { /* compiler enforces Send + Sync */ }
}
```
**The `is_normal` compile-time test.** Pin every important public type so silent auto-trait regressions fail CI rather than downstream builds:
```rust
#[cfg(test)]
fn is_normal<T: Sized + Send + Sync + Unpin>() {}
#[test]
fn public_types_are_normal() {
is_normal::<MyType>();
is_normal::<MyHandle>();
}
```
The test runs no code; it just fails to compile if any listed type loses an auto-trait.
## Object Safety Mechanics
A trait is object-safe (usable as `dyn Trait`) only if every method satisfies all of:
1. **No `Self` by value or as return type.** Rules out `Clone::clone(&self) -> Self`. The vtable doesn't know `Self`'s size.
2. **No generic type parameters on methods.** Rules out `Extend::extend<I: IntoIterator>`. One vtable slot cannot hold infinite monomorphizations.
3. **A `self`/`&self`/`&mut self`/`Box<Self>` receiver.** Rules out `Default::default() -> Self` and other associated functions — no receiver means no impl to pick.
4. **`Sized` must be a non-required supertrait.** `dyn Trait` is unsized; if the trait demands `Self: Sized`, no `dyn` exists.
5. **No associated constants** (without `where Self: Sized`) — same reason as static methods.
Escape hatch: tag the offending method `where Self: Sized`. The method becomes unavailable through `dyn Trait`, but the rest of the trait stays object-safe. `Iterator` uses this trick — `map`, `filter`, `collect`, etc. all carry `where Self: Sized`, which is why `Box<dyn Iterator<Item = T>>` works for `next()` even though most combinators are gone.
If a method genuinely needs a generic, three options before giving up on object safety:
```rust
// Option A: lift the generic to the trait
trait Sink<I> { fn extend(&mut self, iter: I); }
// Option B: take a trait object inside the method
trait Sink { fn extend(&mut self, iter: &mut dyn Iterator<Item = u8>); }
// Option C: opt that one method out of object safety
trait Sink { fn extend<I: IntoIterator<Item = u8>>(&mut self, iter: I) where Self: Sized; }
```
## Wrapper Types and Deref Discipline
`Deref` is appropriate when access is cheap and the wrapper is transparent — the user should be unable to tell the difference between calling a method on the wrapper and on the inner type. Good fits:
- Smart pointers: `Box<T>`, `Rc<T>`, `Arc<T>`, `MutexGuard<'_, T>`.
- Transparent newtypes wrapping a single inner value with no behavior change (`String` derefs to `&str`).
`Deref` is wrong when:
- You want OOP-style inheritance. Rust has none, and `Deref` ambiguity bites: if both your wrapper and its `Deref::Target` have inherent methods named `frobnicate`, `wrapper.frobnicate()` is unambiguous to the compiler but not to the reader. If the target is a *user-controlled* type, any inherent method you add can later clash with one the user adds. Prefer static-form methods (`fn frobnicate(w: Wrapper)`) when forwarding is the goal.
- Access requires complex or expensive logic. `Deref` is implicit; users won't expect `.field` to allocate or hit the network. Provide an explicit accessor instead.
- You are adding behavior rather than forwarding. Use ordinary inherent methods.
`Borrow<T>` vs `AsRef<T>` vs `Deref<Target = T>` are three different contracts. `Borrow` requires that the wrapper produces identical `Hash`, `Eq`, and `Ord` results to the inner — that is why `HashSet<String>` accepts `&str` lookups via `Borrow`. Treat `Borrow` as "equivalent for collection keys," not as a general "I can be referenced as." `AsRef` is the right trait for cheap reference-to-reference conversions without the hash/eq invariant. `Deref` is for transparent dot-operator forwarding.
For a transparent wrapper, eagerly provide all of: `Deref`, `AsRef<Inner>`, `From<Inner>`, `Into<Inner>`.
## Fallible and Blocking Destructors
`Drop::drop(&mut self)` cannot return an error and cannot `.await`. For I/O-flavored types this is a real design constraint. Patterns:
**Explicit `close()` / `shutdown()` method** taking `self` by value and returning `Result<(), Error>` (or `impl Future<Output = Result<...>>`). `Drop` runs as best-effort fallback only. Document the explicit destructor prominently — users won't find it by reading method signatures.
```rust
impl Connection {
pub fn close(self) -> Result<(), CloseError> { /* surfaces errors */ }
}
impl Drop for Connection {
fn drop(&mut self) { let _ = self.try_close_sync(); }
}
```
**The "Drop blocks moves out of self" trap.** Once you implement `Drop`, you cannot move fields out of `self` in other methods, because `Drop::drop(&mut self)` still runs afterward with all fields required intact. Three workarounds:
- **`Option<T>` field**: replace fields (or the whole inner) with `Option`, then `mem::take(&mut self.inner)` (or `Option::take`) in both `Drop` and the explicit destructor. Cost: every field access becomes an unwrap.
- **`std::mem::take`** with a cheap `Default`: swap out the live value during destruction. Tidy when fields have sensible empty defaults.
- **`ManuallyDrop<T>`**: hold the inner in `ManuallyDrop<Inner>` for full manual control. `ManuallyDrop::take` is `unsafe` — double-take or use-after-take is UB. Use only when the code is simple enough to statically verify.
**Never `block_on` in `Drop`.** Spawning a runtime or blocking on one inside a destructor deadlocks under async runtimes and races executor shutdown. Provide an explicit `async fn close(self) -> Result<...>` and document that callers must invoke it.
## Ergonomic Blanket Impls
Rust does not auto-implement traits for references or smart pointers. So `fn f<T: MyTrait>(t: T)` rejects `&Wrapper` even when `Wrapper: MyTrait`. When you define a new trait, eagerly add the blanket impls users expect — adding them later is a breaking change because of coherence rules (downstream impls may already overlap).
For a trait whose methods all take `&self`:
```rust
impl<T: MyTrait + ?Sized> MyTrait for &T { /* forward */ }
impl<T: MyTrait + ?Sized> MyTrait for &mut T { /* forward */ }
impl<T: MyTrait + ?Sized> MyTrait for Box<T> { /* forward */ }
```
Which blankets are possible depends on the receivers. `&mut self` rules out `&T`. `self` rules out all three. Include `?Sized` so unsized types (`dyn`, `str`, slices) work too.
For iterable collections, also provide both reference forms of `IntoIterator` so `for x in &c` and `for x in &mut c` work as users expect from `Vec` and `HashMap`:
```rust
impl<'a, T> IntoIterator for &'a MyCollection<T> { /* type Item = &'a T; */ }
impl<'a, T> IntoIterator for &'a mut MyCollection<T> { /* type Item = &'a mut T; */ }
```
## Standard Derives Priority — Ordered List
The intro section above lists the basics. Jon's full ordering with caveats:
- **`Debug`** — first, nearly every type. If `#[derive(Debug)]` adds an unwanted `T: Debug` bound (e.g., `T` is only used as `PhantomData`), hand-write the impl via `f.debug_struct(...)`.
- **`Send` / `Sync` / `Unpin`** — auto-derived from contents. If a type is intentionally `!Send` or `!Sync`, document why in rustdoc. Non-`Send` types cannot live in `Mutex` or tokio tasks; non-`Sync` types cannot live in `Arc` or `static`.
- **`Clone` / `Default`** — expected for most types. Easy to derive; document explicitly if a type cannot implement them.
- **`PartialEq`** — high value; users want `assert_eq!`. Worth implementing even when equality is reflexive-only.
- **`Eq` / `Hash`** — for map and set keys. `Eq` carries reflexivity beyond `PartialEq`; only add when the semantics hold.
- **`PartialOrd` / `Ord`** — only when a natural total order exists. Most types don't qualify.
- **`Serialize` / `Deserialize`** — gate behind `#[cfg_attr(feature = "serde", derive(...))]` so consumers opt into the serde dependency.
**Avoid `Copy` by default.** Users expect to call `.clone()` for a second copy. `Copy` changes move semantics and is highly restrictive — a type that starts simple often grows to hold a `String`, and removing `Copy` is a breaking change. `Clone` is far easier to keep stable across versions.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |