290 lines
6.3 KiB
Markdown
290 lines
6.3 KiB
Markdown
---
|
|
name: rust
|
|
description: "Language-specific super-code guidelines for rust."
|
|
risk: safe
|
|
source: community
|
|
date_added: "2026-06-16"
|
|
---
|
|
# Rust: Idiomatic Efficiency Reference
|
|
|
|
## Table of Contents
|
|
1. [Ownership & Borrowing](#ownership)
|
|
2. [Error Handling](#errors)
|
|
3. [Iterators](#iterators)
|
|
4. [Pattern Matching](#patterns)
|
|
5. [Structs & Enums](#structs)
|
|
6. [Concurrency](#concurrency)
|
|
7. [Anti-patterns specific to Rust](#antipatterns)
|
|
|
|
---
|
|
|
|
## 1. Ownership & Borrowing {#ownership}
|
|
|
|
```rust
|
|
// ❌ Cloning to avoid thinking about lifetimes
|
|
fn get_name(user: &User) -> String {
|
|
user.name.clone()
|
|
}
|
|
|
|
// ✅ — return a reference when the data lives long enough
|
|
fn get_name(user: &User) -> &str {
|
|
&user.name
|
|
}
|
|
```
|
|
|
|
```rust
|
|
// ❌ Taking ownership when borrowing suffices
|
|
fn print_name(name: String) {
|
|
println!("{name}");
|
|
}
|
|
|
|
// ✅
|
|
fn print_name(name: &str) {
|
|
println!("{name}");
|
|
}
|
|
```
|
|
|
|
```rust
|
|
// ❌ Unnecessary .to_string() / .to_owned() in hot paths
|
|
let key = id.to_string();
|
|
map.get(&key)
|
|
|
|
// ✅ — use Borrow trait; HashMap<String, V> accepts &str as key
|
|
map.get(id)
|
|
```
|
|
|
|
**Prefer `&str` over `String` in function parameters unless the function needs to own the data.**
|
|
|
|
---
|
|
|
|
## 2. Error Handling {#errors}
|
|
|
|
```rust
|
|
// ❌ .unwrap() in production code
|
|
let file = File::open(path).unwrap();
|
|
|
|
// ✅
|
|
let file = File::open(path)
|
|
.map_err(|e| AppError::Io { path: path.to_owned(), source: e })?;
|
|
```
|
|
|
|
```rust
|
|
// ❌ Manual match on Result for every call
|
|
match do_thing() {
|
|
Ok(v) => v,
|
|
Err(e) => return Err(e),
|
|
}
|
|
|
|
// ✅ — the ? operator
|
|
let v = do_thing()?;
|
|
```
|
|
|
|
```rust
|
|
// ❌ Box<dyn Error> everywhere (loses type info)
|
|
fn run() -> Result<(), Box<dyn std::error::Error>> { ... }
|
|
|
|
// ✅ — use thiserror for library errors, anyhow for application errors
|
|
use anyhow::{Context, Result};
|
|
fn run() -> Result<()> {
|
|
do_thing().context("failed during run")?;
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
```rust
|
|
// ❌ Separate error enum variant for every call site
|
|
enum Error { FileOpen, FileRead, Parse, Network, ... }
|
|
|
|
// ✅ — use thiserror with #[from] for automatic conversion
|
|
#[derive(thiserror::Error, Debug)]
|
|
enum Error {
|
|
#[error("io error")] Io(#[from] std::io::Error),
|
|
#[error("parse error")] Parse(#[from] serde_json::Error),
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Iterators {#iterators}
|
|
|
|
```rust
|
|
// ❌ Imperative accumulation
|
|
let mut result = Vec::new();
|
|
for item in &items {
|
|
if item.active {
|
|
result.push(item.name.to_uppercase());
|
|
}
|
|
}
|
|
|
|
// ✅
|
|
let result: Vec<_> = items.iter()
|
|
.filter(|i| i.active)
|
|
.map(|i| i.name.to_uppercase())
|
|
.collect();
|
|
```
|
|
|
|
```rust
|
|
// ❌ Manual sum
|
|
let mut total = 0;
|
|
for order in &orders { total += order.amount; }
|
|
|
|
// ✅
|
|
let total: u64 = orders.iter().map(|o| o.amount).sum();
|
|
```
|
|
|
|
```rust
|
|
// ❌ Index-based loop
|
|
for i in 0..items.len() {
|
|
process(&items[i]);
|
|
}
|
|
|
|
// ✅
|
|
for item in &items {
|
|
process(item);
|
|
}
|
|
// With index:
|
|
for (i, item) in items.iter().enumerate() {
|
|
process(i, item);
|
|
}
|
|
```
|
|
|
|
**Chain iterators lazily; only `.collect()` when you actually need a concrete collection.**
|
|
|
|
---
|
|
|
|
## 4. Pattern Matching {#patterns}
|
|
|
|
```rust
|
|
// ❌ if-let chain that should be match
|
|
if let Some(x) = opt {
|
|
if x > 0 {
|
|
use(x)
|
|
}
|
|
}
|
|
|
|
// ✅
|
|
if let Some(x) = opt.filter(|&x| x > 0) {
|
|
use(x)
|
|
}
|
|
// or match with guard:
|
|
match opt {
|
|
Some(x) if x > 0 => use(x),
|
|
_ => {}
|
|
}
|
|
```
|
|
|
|
```rust
|
|
// ❌ match with identical arms
|
|
match status {
|
|
Status::Active => true,
|
|
Status::Pending => true,
|
|
Status::Inactive => false,
|
|
}
|
|
|
|
// ✅
|
|
matches!(status, Status::Active | Status::Pending)
|
|
```
|
|
|
|
```rust
|
|
// ❌ Destructuring in body instead of pattern
|
|
fn area(shape: &Shape) -> f64 {
|
|
match shape {
|
|
Shape::Circle(c) => { let r = c.radius; r * r * PI }
|
|
Shape::Rect(r) => { let w = r.width; let h = r.height; w * h }
|
|
}
|
|
}
|
|
|
|
// ✅ — destructure in pattern
|
|
match shape {
|
|
Shape::Circle(Circle { radius, .. }) => radius * radius * PI,
|
|
Shape::Rect(Rect { width, height }) => width * height,
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Structs & Enums {#structs}
|
|
|
|
```rust
|
|
// ❌ Enum variant carrying bool for binary state
|
|
enum State { Running(bool) } // true = paused?
|
|
|
|
// ✅ — explicit variants
|
|
enum State { Running, Paused, Stopped }
|
|
```
|
|
|
|
```rust
|
|
// ❌ Struct with many Option fields (stringly optional)
|
|
struct Config {
|
|
timeout: Option<u64>,
|
|
retries: Option<u32>,
|
|
base_url: Option<String>,
|
|
}
|
|
|
|
// ✅ — use Default + builder pattern or #[derive(Default)] with sensible defaults
|
|
#[derive(Default)]
|
|
struct Config {
|
|
timeout: u64, // default 0 = no timeout
|
|
retries: u32, // default 0
|
|
base_url: String,
|
|
}
|
|
```
|
|
|
|
```rust
|
|
// ❌ pub fields on a type that needs invariants
|
|
pub struct Percentage { pub value: f64 }
|
|
|
|
// ✅ — private field, constructor enforces invariant
|
|
pub struct Percentage(f64);
|
|
impl Percentage {
|
|
pub fn new(v: f64) -> Option<Self> {
|
|
(0.0..=100.0).contains(&v).then_some(Self(v))
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Concurrency {#concurrency}
|
|
|
|
```rust
|
|
// ❌ Arc<Mutex<T>> for read-heavy data
|
|
let data = Arc::new(Mutex::new(vec![...]));
|
|
|
|
// ✅ — RwLock for read-heavy
|
|
let data = Arc::new(RwLock::new(vec![...]));
|
|
```
|
|
|
|
```rust
|
|
// ❌ Spawning OS threads for many small tasks
|
|
for item in items {
|
|
std::thread::spawn(|| process(item));
|
|
}
|
|
|
|
// ✅ — use rayon for CPU-bound parallel iteration
|
|
use rayon::prelude::*;
|
|
items.par_iter().for_each(|item| process(item));
|
|
```
|
|
|
|
**For async: prefer `tokio::spawn` + `JoinHandle` over manual channels for structured concurrency. Use `tokio::join!` for concurrent awaits.**
|
|
|
|
---
|
|
|
|
## 7. Anti-patterns specific to Rust {#antipatterns}
|
|
|
|
| Anti-pattern | Preferred |
|
|
|---|---|
|
|
| `.clone()` to appease borrow checker | reconsider lifetime or restructure |
|
|
| `.unwrap()` in non-test code | `?` operator or explicit handling |
|
|
| `impl Trait` in return position hiding complex type | name the type or use `Box<dyn Trait>` intentionally |
|
|
| `String` parameter when `&str` suffices | `&str` for params, `String` for owned storage |
|
|
| Nested `Option<Option<T>>` | rethink the data model |
|
|
| `unsafe` block without a safety comment | always document the invariant being upheld |
|
|
| `Vec<Box<T>>` when `Vec<T>` works | avoid heap allocation inside collections unless T is unsized |
|
|
| Manual `Drop` for cleanup that `?` handles | let RAII + `?` do it |
|
|
|
|
|
|
## Limitations
|
|
- These are language-specific guidelines and do not cover overall architectural decisions.
|
|
- Over-compression might reduce readability; apply judgement.
|