massimodeluisa/rust-best-practices-skill / skills/rust-best-practices
rust-best-practices
VerifiedWrite and review production Rust using the official API Guidelines, Style Guide, and this engineering standard: allocation contracts, ownership, Result vs panic, debug_assert, Clippy, tests, rustdoc, unsafe, and Cargo CI. Use when writing, reviewing, or refactoring Rust; choosing borrow vs clone; designing crate APIs; handling errors; bounding heap use; configuring clippy or rustfmt; or when the user runs /rust-best-practices. Do not use for other languages. Triggers: rust, rustc, cargo, clippy, rustfmt, ownership, clone, borrow, Result, unwrap, expect, panic, thiserror, anyhow, heapless, no_std, allocation, debug_assert, type-state, Send, Sync, unsafe, FFI, rustdoc, MSRV, rust-best-practices, rust style, rust guidelines
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.0 KB |
| evals/evals.json | config | 3.2 KB |
| references/allocation.md | markdown | 10.2 KB |
| references/design.md | markdown | 7.9 KB |
| references/errors.md | markdown | 6.8 KB |
| references/official.md | markdown | 8.1 KB |
| references/ownership.md | markdown | 3.9 KB |
| references/performance.md | markdown | 3.1 KB |
| references/quality.md | markdown | 10.9 KB |
| references/review.md | markdown | 4.4 KB |
| references/unsafe.md | markdown | 3.3 KB |
references/errors.md
View on GitHub# Errors, panics, arithmetic, and `debug_assert!`
## `Option` for absence, `Result` for failure
Do not encode absence with empty strings, zero IDs, negative numbers, or invalid pointers.
```rust
pub fn record_at(records: &[Record], index: usize) -> Result<&Record, LookupError> {
let record = records.get(index).ok_or(LookupError::OutOfBounds {
index,
len: records.len(),
})?;
debug_assert!(index < records.len());
Ok(record)
}
```
Use combinators when they improve clarity. Use `match`, `if let`, or `let ... else` when control flow or error context is clearer explicitly.
### Pattern choice
- `match` when you need the inner `T` / `E` variants or a type change (`Result<T, E>` to `Result<Option<T>, E>`).
- `let PATTERN = EXPR else { diverging }` when the else is `return` / `continue` / `break` and does not need extra computation on the failed value.
- `if let` when both branches do real work.
- `?` when you do not need the `Err` value and policy is "propagate".
Prefer `.ok()`, `.ok_or()`, `.ok_or_else()` over a `match` that only converts `Result` to `Option`.
For `Result::Err` that must be logged then translated: `inspect_err` then `map_err`.
## No `unwrap` / `expect` on production paths
Production libraries MUST NOT use `unwrap()` or `expect()` for recoverable conditions. Tests, examples that demonstrate panic, and compile-time-proven constants MAY use them sparingly; a clearer assertion is often better.
Do not convert a recoverable error into a panic because handling it is inconvenient.
Prefer:
```rust
let Ok(json) = serde_json::from_str(&input) else {
return Err(MyError::InvalidJson);
};
```
`unwrap_or` / `unwrap_or_else` / `unwrap_or_default` when a fallback value is the contract.
## Panic only for programmer defects
Caller-controlled input, malformed artifacts, capacity exhaustion, I/O failures, and unavailable resources are not programmer defects. Return a typed error.
A panic MAY be appropriate when an internal invariant is violated and continuing would indicate a defect. In libraries, keep panic conditions rare and document them under `# Panics` ([C-FAILURE](https://rust-lang.github.io/api-guidelines/documentation.html#c-failure)).
`todo!`, `unreachable!`, `unimplemented!` are explicit; they are still panics. Do not leave them on production paths.
## Typed library errors
Library errors SHOULD be focused, stable, and domain-specific. Do not expose a third-party error type as the core public contract unless that coupling is intentional ([C-GOOD-ERR](https://rust-lang.github.io/api-guidelines/interoperability.html#c-good-err)).
In strict or allocation-free code, error context MUST stay allocation-free (copyable enums, no `String` payload). See [allocation.md](allocation.md).
`thiserror` MAY be used for allocating or `std`-facing crates when compatible with MSRV and feature policy:
```rust
#[derive(Debug, thiserror::Error)]
pub enum ServiceError {
#[error("database: {0}")]
Db(#[from] DbError),
#[error("invalid data: {0}")]
InvalidData(String),
}
```
Layered systems: nested enums with `#[from]`. A module with a single failure mode MAY use a struct error instead of a one-variant enum.
`anyhow` is for binary / application boundaries, not core library APIs or strict heapless code. `anyhow::Result` erases context callers need. Keep `context` strings from drifting; prefer a typed error with one `Display`.
Async: errors crossing `.await` or tasks MUST be `Send + Sync + 'static` where the runtime requires it. Avoid `Box<dyn std::error::Error>` in libraries unless required.
## `?` without hiding policy
Prefer `?` for straightforward propagation. Do not use it to hide translation, retry, rollback, or cleanup:
```rust
let header = parse_header(input)?;
let body = parse_body(input, header.body_range).map_err(ParsePacketError::Body)?;
```
## Checked arithmetic at trust boundaries
Offsets, lengths, capacities, and serialized values MUST use checked arithmetic before indexing or allocation decisions.
```rust
let end = start.checked_add(length).ok_or(ParseError::IntegerOverflow)?;
if end > input.len() {
return Err(ParseError::OffsetOutOfBounds {
offset: end,
input_len: input.len(),
});
}
debug_assert!(start <= end);
debug_assert!(end <= input.len());
```
Document overflow semantics for domain arithmetic: checked and erroring, saturating, wrapping, or explicitly proven impossible. Do not rely on debug-only overflow as the release contract.
## `debug_assert!` for internal invariants
Use `debug_assert!`, `debug_assert_eq!`, `debug_assert_ne!` when **all** of these hold:
1. The condition is established by types or release-active control flow.
2. It is a programming invariant, not caller validation.
3. Release correctness does not depend on the assertion executing.
4. Removing it cannot introduce undefined behavior.
5. Evaluating it has no required side effects.
6. The condition and message do not intentionally allocate.
Good: `debug_assert!(cursor <= input.len())` after a checked bounds calculation.
Use after important state transitions, checked bounds, fixed-capacity writes, parser cursor movement, and canonicalization, when they detect real defects. Do not add assertions mechanically.
Docs: [`debug_assert!`](https://doc.rust-lang.org/std/macro.debug_assert.html).
### External input: all builds
Incorrect:
```rust
pub fn read_byte(input: &[u8], index: usize) -> u8 {
debug_assert!(index < input.len());
input[index]
}
```
Correct: `get` + typed error, then `debug_assert!` on the established invariant.
### NEVER as an `unsafe` precondition
```rust
// Incorrect: the proof disappears in optimized builds.
debug_assert!(index < values.len());
let value = unsafe { *values.get_unchecked(index) };
```
Unsafe MUST rely on types, release-active validation, or a documented invariant proven independently of debug assertions. A debug assertion MAY duplicate a valid proof; it cannot be the proof.
### No required side effects
Incorrect: `debug_assert!(advance_cursor(&mut cursor));`
Correct: run the update, then `debug_assert!(advanced);`
The program MUST behave correctly with assertions on or off.
### Allocation-aware diagnostics
Prefer simple conditions and static messages. Avoid `input.to_vec()` or `state.to_string()` inside the assertion. `debug_assert_eq!` formats `Debug` on failure; custom `Debug` MUST NOT allocate on strict paths.
### Invariant panic is not a recoverable path
Panic hooks, backtraces, and diagnostics MAY allocate. An allocation-free guarantee covers success, documented recoverable errors, capacity exhaustion, and malformed input. An internal invariant panic is a defect path.
### Test optimized code with assertions on
```toml
[profile.release-assertions]
inherits = "release"
debug-assertions = true
overflow-checks = true
```
```bash
cargo test --workspace --profile release-assertions
```
CI: [quality.md](quality.md).
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 |