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/documentation.md

View on GitHub
# Documentation

## Comments vs Doc Comments

| Purpose | `// comment` | `/// doc` / `//! crate doc` |
|---------|-------------|---------------------------|
| Describe why | Yes -- explains reasoning | No |
| Describe API | No | Yes -- public interfaces, usage |
| Maintainable | Gets stale, not compiled | Tied to code, appears in `cargo doc` |
| Testable | No | Yes -- doc examples run with `cargo test` |
| Visibility | Local to source | Exported to users and tools |

## When to Use `//` Comments

Use when something can't be expressed clearly in code:

```rust
// SAFETY: ptr is guaranteed non-null and aligned by caller contract
unsafe { std::ptr::copy_nonoverlapping(src, dst, len); }

// PERF: Caching root cert store avoids repeated OS calls on macOS
// See ADR-12: TLS startup latency
let tls_store = cached_root_store();
```

### Good Comments

- Safety invariants: `// SAFETY: ...`
- Performance reasoning: `// PERF: ...`
- Design context: `// CONTEXT: See ADR-42 for rationale`
- Workarounds: `// WORKAROUND: upstream bug #123`

### Bad Comments

```rust
// BAD - restates the obvious
counter += 1; // increment counter by 1

// BAD - wall of text that should be a doc comment or ADR
// This function was originally written in 2023 for the legacy API...
// [20 more lines of history]
```

## Replace Comments with Code

If you're writing a long comment explaining "what" or "how", refactor instead:

```rust
// DON'T
fn process_request(req: Request) -> Result<(), Error> {
    // validate headers, then decode body, then authorize, then dispatch
    // ...100 lines...
}

// DO
fn process_request(req: Request) -> Result<(), Error> {
    validate_headers(&req)?;
    let body = decode_body(&req)?;
    authorize(&body)?;
    dispatch(body)
}
```

Structure and naming replace commentary. Tests serve as living documentation.

## TODO Discipline

Don't leave orphan TODOs. Link to a tracked issue:

```rust
// TODO(#42): Remove workaround after upstream fix lands
```

## When to Use `///` Doc Comments

Document all public items: functions, structs, traits, enums, constants.

```rust
/// Loads a user profile from disk.
///
/// # Errors
///
/// Returns [`AppError::NotFound`] if the file is missing.
/// Returns [`AppError::InvalidFormat`] if the content is not valid JSON.
///
/// # Examples
///
/// ```rust
/// # use my_crate::load_user;
/// let user = load_user("profiles/alice.json")?;
/// assert_eq!(user.name, "Alice");
/// # Ok::<(), my_crate::AppError>(())
/// ```
pub fn load_user(path: &str) -> Result<User, AppError> { /* ... */ }
```

### Required Sections

- **Purpose** -- what the item does (first line)
- **`# Examples`** -- runnable code showing usage
- **`# Errors`** -- when it returns `Err` (for Result-returning functions)
- **`# Panics`** -- when it can panic (if applicable)
- **`# Safety`** -- invariants for `unsafe` functions

### Doc Test Tips

- Hide setup lines with `#` prefix
- Examples run with `cargo test` (but NOT `cargo nextest` -- run `cargo test --doc` separately)
- Use `compile_fail` attribute for wrong-usage examples
- Use `no_run` for side-effect examples (network, file I/O)

## Module-Level Docs with `//!`

Place at the top of `lib.rs` or `mod.rs`:

```rust
//! HTTP client with retry and circuit-breaker support.
//!
//! This module provides a resilient HTTP client that wraps `reqwest`
//! with automatic retries and circuit-breaker patterns.
//!
//! # Examples
//!
//! ```rust
//! let client = http::Client::builder().retries(3).build();
//! let response = client.get("https://api.example.com").await?;
//! ```
```

## Custom Error Messages with `#[diagnostic::on_unimplemented]`

Since Rust 1.78, you can provide custom compiler error messages when a trait is not implemented. This dramatically improves developer experience for library traits:

```rust
#[diagnostic::on_unimplemented(
    message = "`{Self}` is not a valid handler function",
    label = "this type does not implement `Handler`",
    note = "Handler functions must accept a `Request` and return `impl IntoResponse`"
)]
trait Handler {
    fn call(&self, req: Request) -> Response;
}
```

When someone tries to use a type that doesn't implement `Handler`, they see your custom message instead of the generic "trait bound not satisfied" error.

Use this for:
- Public library traits where users frequently hit confusing errors
- Trait bounds with non-obvious requirements (e.g., axum handlers, tower services)
- Domain-specific traits where the fix is not obvious from the trait name

## Documentation Lints

Enable for library crates:

```rust
// In lib.rs
#![deny(missing_docs)]
```

| Lint | Purpose |
|------|---------|
| `missing_docs` | Warn on undocumented public items |
| `broken_intra_doc_links` | Detect broken `[links]` in doc comments |
| `missing_panics_doc` | Require `# Panics` section when function can panic |
| `missing_errors_doc` | Require `# Errors` for Result-returning functions |
| `missing_safety_doc` | Require `# Safety` for unsafe public functions |
| `empty_docs` (clippy) | Prevent empty doc comments that bypass `missing_docs` |

Run `cargo doc --open` to preview your documentation output.

## Checklist

- [ ] All public items have `///` doc comments
- [ ] `//!` at top of lib.rs/mod.rs explaining purpose
- [ ] `# Examples` with runnable code on key functions
- [ ] `# Errors` and `# Panics` sections where applicable
- [ ] `// SAFETY:` comments on all `unsafe` blocks
- [ ] No stale comments that describe old behavior
- [ ] Every `TODO` links to a tracked issue
- [ ] `#![deny(missing_docs)]` enabled for library crates
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: 198kUpdated Claude CodeCodexVerifiedInstall