Skip to content

existential-birds/beagle / plugins/beagle-rust/skills/rust-best-practices

rust-best-practices

Verified

Development 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.

references/generics-dispatch.md

View on GitHub
# Generics and Dispatch

## Static Dispatch: `impl Trait` / `<T: Trait>`

Generics are monomorphized at compile time -- the compiler generates specialized code for each concrete type. Zero runtime cost.

### Use When

- Performance-critical code (tight loops, hot paths)
- Types are known at compile time
- You want inlining and optimization

```rust
// Generic function -- compiler generates specialized versions
fn process<T: Display>(item: T) {
    println!("{item}");
}

// Equivalent modern syntax
fn process(item: impl Display) {
    println!("{item}");
}
```

## Dynamic Dispatch: `dyn Trait`

Uses a vtable (virtual function table) for runtime polymorphism. Incurs indirection cost per call.

### Use When

- Heterogeneous collections (different types in one `Vec`)
- Plugin architectures with runtime-loaded components
- Abstracting internals behind a stable public interface
- Binary size matters more than call performance

```rust
// Different types in one collection
fn greet_all(animals: &[Box<dyn Animal>]) {
    for animal in animals {
        println!("{}", animal.greet());
    }
}
```

## Trade-Off Table

| Aspect | Static (`impl Trait`) | Dynamic (`dyn Trait`) |
|--------|----------------------|----------------------|
| Performance | Faster, inlined | Slower, vtable indirection |
| Compile time | Slower (monomorphization) | Faster (shared code) |
| Binary size | Larger (per-type codegen) | Smaller |
| Flexibility | One type at a time | Mix types in collections |
| Error messages | Clearer | Type erasure obscures errors |

## Decision Guide

1. **Start with generics.** They are the default in Rust.
2. **Switch to `dyn Trait`** when you need runtime polymorphism or heterogeneous collections.
3. If unsure, use generics with trait bounds -- refactor to `dyn` only when flexibility outweighs speed.

## Best Practices for Dynamic Dispatch

### Pointer Choice

```rust
// Prefer &dyn Trait when you don't need ownership
fn log(writer: &dyn Write) { /* ... */ }

// Use Box<dyn Trait> when you need to own the value
fn create_handler() -> Box<dyn Handler> { /* ... */ }

// Use Arc<dyn Trait> for shared access across threads
fn register(service: Arc<dyn Service>) { /* ... */ }
```

### Don't Box Too Early

```rust
// DO - use generics when possible
struct Renderer<B: Backend> {
    backend: B,
}

// DON'T - premature boxing reduces performance and flexibility
struct Renderer {
    backend: Box<dyn Backend>,
}
```

Box at API boundaries (public return types), not inside structs.

### Object Safety Rules

You can only create `dyn Trait` from object-safe traits:

- No generic methods
- No `Self: Sized` bound
- All methods use `&self`, `&mut self`, or `self`

```rust
// Object-safe -- can use as dyn
trait Runnable {
    fn run(&self);
}

// NOT object-safe -- generic method
trait Factory {
    fn create<T>(&self) -> T;
}
```

## RPIT Lifetime Capture (Edition 2024)

In Rust 2024, `-> impl Trait` return types capture ALL in-scope generic parameters and lifetimes by default. Previously (edition 2021), hidden types only captured the generic parameters explicitly mentioned in the opaque type.

### What Changed

```rust
// Edition 2021: 'a is NOT captured, return type outlives 'a
fn foo<'a>(x: &'a str) -> impl Display {
    x.len() // returns usize, no lifetime dependency
}

// Edition 2024: 'a IS captured by default, return type borrows 'a
fn foo<'a>(x: &'a str) -> impl Display {
    x.len() // still returns usize, but type signature now captures 'a
}
```

### Precise Capturing with `+ use<>`

When you need to opt out of capturing a lifetime or generic, use the `+ use<>` syntax:

```rust
// Only capture T, not the lifetime 'a
fn extract<'a, T: Display>(data: &'a [T]) -> impl Display + use<T> {
    data.len()
}

// Capture nothing -- equivalent to edition 2021 behavior
fn compute<'a>(x: &'a str) -> impl Display + use<> {
    x.len()
}
```

Use `+ use<>` when the return type genuinely does not depend on a lifetime, and callers need the returned value to outlive the borrow.

## Async Functions in Traits

Since Rust 1.75, `async fn` works directly in traits without the `async-trait` crate for many use cases:

```rust
// GOOD (Rust 1.75+) -- native async fn in trait
trait DataStore {
    async fn get(&self, key: &str) -> Option<String>;
    async fn put(&self, key: &str, value: &str) -> Result<(), StoreError>;
}

// BAD -- unnecessary async-trait dependency
#[async_trait::async_trait]
trait DataStore {
    async fn get(&self, key: &str) -> Option<String>;
    async fn put(&self, key: &str, value: &str) -> Result<(), StoreError>;
}
```

### When You Still Need `async-trait`

- **`dyn Trait` dispatch** -- native async fn in traits is not yet object-safe. If you need `Box<dyn DataStore>`, you still need `async-trait` or manual boxing.
- **Older MSRV** -- if your minimum supported Rust version is below 1.75.

For most application code with static dispatch, drop `async-trait` and use native syntax.

## Patterns

### Accept Generic, Return Concrete

Public APIs often accept generics for flexibility but return concrete types:

```rust
pub fn parse(input: impl AsRef<str>) -> Result<Config, ParseError> {
    let s = input.as_ref();
    // ...
}
```

### Trait Bounds on Impl Blocks

Constrain methods to specific trait implementations:

```rust
struct Wrapper<T>(T);

impl<T: Display> Wrapper<T> {
    fn show(&self) {
        println!("{}", self.0);
    }
}

impl<T: Display + Debug> Wrapper<T> {
    fn debug_show(&self) {
        println!("{:?}", self.0);
    }
}
```

### Where Clauses for Readability

```rust
// Hard to read
fn process<T: Clone + Debug + Send + Sync + 'static>(item: T) { /* ... */ }

// Clearer
fn process<T>(item: T)
where
    T: Clone + Debug + Send + Sync + 'static,
{
    // ...
}
```

## Variance Rules for Generics

Variance determines how subtyping relationships carry through generic types.

| Variance | Rule | Example |
|----------|------|---------|
| Covariant | If `'a: 'b`, then `T<'a>: T<'b>` | `&'a T`, `Vec<T>`, `Box<T>` |
| Contravariant | If `'a: 'b`, then `T<'b>: T<'a>` | `fn(T)` (in argument position) |
| Invariant | No subtyping relationship | `&'a mut T`, `Cell<T>`, `UnsafeCell<T>` |

**Practical impact:** `&'a mut T` is invariant over `T`, meaning you cannot coerce `&mut Vec<&'static str>` to `&mut Vec<&'a str>`. This prevents unsoundness where a shorter-lived reference could be inserted through the mutable alias.

Prefer `&T` (covariant) over `&mut T` (invariant) in generic contexts when mutation is not needed -- it gives callers more flexibility with lifetimes.

## Trait Object Cost Analysis

Dynamic dispatch via `dyn Trait` introduces two costs:

1. **Vtable indirection** -- each method call goes through a pointer lookup instead of a direct call. Prevents inlining and limits compiler optimizations.
2. **Loss of monomorphization** -- the compiler cannot specialize code per concrete type, eliminating opportunities for constant folding and layout optimization.

The overhead per call is typically 1-3 ns (vtable pointer chase). Avoid `dyn Trait` in tight loops or hot paths. Use it freely at architectural boundaries where call frequency is low.

## Object Safety Rules

A trait is object-safe (usable as `dyn Trait`) only when all methods satisfy:

- **No generic type parameters** on methods (generic params on the trait itself are fine)
- **No use of `Self` as a concrete type** in arguments or return position
- **No `Self: Sized` bound** on the trait itself (individual methods can have it)
- **Receivers must be dispatchable:** `&self`, `&mut self`, `self`, `Box<Self>`, `Arc<Self>`, `Pin<&Self>`, etc.

```rust
// NOT object-safe -- generic method prevents vtable construction
trait Parser {
    fn parse<T: FromStr>(&self, input: &str) -> T;
}

// Fix: exempt the generic method, keep the trait object-safe
trait Searchable {
    fn search(&self, query: &str) -> Vec<String>;
    fn search_typed<T>(&self, query: &str) -> Vec<T> where Self: Sized;
    // ^^ only callable on concrete types; dyn Searchable still works for search()
}
```

Prefer keeping traits object-safe. Add `where Self: Sized` to convenience methods that break object safety rather than sacrificing the whole trait.

## Complete Dispatch Decision Tree

```text
Do you need different concrete types in the same collection or behind one pointer?
  YES -> dyn Trait (dynamic dispatch)
    -> Need ownership? Box<dyn Trait>
    -> Borrowed only? &dyn Trait
    -> Shared across threads? Arc<dyn Trait>
  NO -> Do callers need to name the concrete return type?
    YES -> Generic <T: Trait> (full monomorphization)
    NO  -> impl Trait (opaque type, still static dispatch)
```

**`impl Trait` vs `dyn Trait` vs `T: Trait` summary:**

| Feature | `T: Trait` | `impl Trait` | `dyn Trait` |
|---------|-----------|-------------|-------------|
| Dispatch | Static | Static | Dynamic |
| Caller picks type | Yes | Arg: yes, Return: no | No (type-erased) |
| Turbofish (`::<>`) | Yes | No | N/A |
| Multiple types in collection | No | No | Yes |
| Binary size impact | Larger (codegen per type) | Larger | Smaller |
| Use in trait definitions | Yes | Limited | Yes |

## Blanket Implementation Patterns

Blanket impls provide automatic trait implementations for broad categories of types. Use them to reduce boilerplate, but be aware of their downstream impact.

```rust
// Common: forward trait through references
impl<T: MyTrait> MyTrait for &T {
    fn method(&self) { (**self).method() }
}

// Common: forward through smart pointers
impl<T: MyTrait + ?Sized> MyTrait for Box<T> {
    fn method(&self) { (**self).method() }
}

// Powerful but constraining: implement for all types meeting a bound
impl<T: Display> Loggable for T {
    fn log(&self) { println!("{self}"); }
}
```

**Impact on downstream users:** a blanket impl prevents anyone from writing a more specific impl for the same trait. Once `impl<T: Display> Loggable for T` exists, no one can write `impl Loggable for MyType` even if `MyType: Display`. Plan blanket impls carefully -- adding one later is a breaking change due to coherence rules.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall