Testing
- Unit tests in
#[cfg(test)]modules within each source file - Integration tests in
tests/directory
Naming
- No
get_prefix:fn name()notfn get_name() - Iterator convention:
iter()/iter_mut()/into_iter() - Conversion naming:
as_(cheap &),to_(expensive),into_(ownership) - Static var prefix:
G_CONFIGforstatic, no prefix forconst
Data Types
- Use newtypes:
struct Email(String)for domain semantics - Prefer slice patterns:
if let [first, .., last] = slice - Pre-allocate:
Vec::with_capacity(),String::with_capacity() - Avoid
Vecabuse: use arrays for fixed sizes
Strings
- Prefer
&stroverStringin function parameters - Use
Stringfor ownership: returnStringwhen transferring ownership - Prefer bytes:
s.bytes()overs.chars()when ASCII - Use
Cow<str>when you might need to modify borrowed data - Use
format!over string concatenation with+ - Avoid nested iteration:
contains()on string is O(n*m)
Error Handling
- Use
?for all fallible operations unwrap()in tests only, never productionexpect()only for provably impossible states; the message must justify why it can't fail e.g.expect("regex is valid: validated at compile time")unwrap_or/unwrap_or_else/unwrap_or_defaultfor deliberate fallbacks- Assertions for invariants:
assert!at function entry
Memory
- Meaningful lifetimes:
'src,'ctxnot just'a try_borrow()for RefCell to avoid panic- Shadowing for transformation:
let x = x.parse()?
Concurrency
- Identify lock ordering to prevent deadlocks
- Atomics for primitives, not Mutex for bool/usize
- Choose memory order carefully: Relaxed/Acquire/Release/SeqCst
Async
- Sync for CPU-bound; async is for I/O
- Don't hold locks across await: use scoped guards
Macros
- Avoid unless necessary: prefer functions/generics
- Follow Rust syntax: macro input should look like Rust
Deprecated → Better
lazy_static!→std::sync::OnceLock(since 1.70)once_cell::Lazy→std::sync::LazyLock(since 1.80)std::sync::mpsc→crossbeam::channelonly if you need multi-consumer or better performance under contention;std::sync::mpscis fine for most use casesfailure/error-chain→thiserror/anyhowtry!()→?operator (since 2018)
Docs
- All
pubmethods must have///doc comments - All
///doc comments must be extremely concise - Imperative mood:
Returns the lengthnotThis function returns the length - Don't restate the name:
fn connect()doesn't need "Connects to the server" - Document the non-obvious: panics, errors, surprising edge cases; skip obvious params/returns
- No filler: no "This method...", "Note that...", "Please be aware..."
# Examplesonly for non-trivial usage; doctests must compile and pass- Don't write doctests purely for coverage; write them only when the example genuinely aids understanding
Quick Reference
Naming: snake_case (fn/var), CamelCase (type), SCREAMING_CASE (const)
Format: rustfmt (just use it)
Docs: /// for public items, //! for module docs
Lint: #![deny(clippy::all, clippy::pedantic)]
Miscellaneous
- Derive
Debugon all public types; deriveClone,PartialEqonly when needed - Use clippy with
#![deny(clippy::all, clippy::pedantic)]- fix all warnings - No unsafe blocks
- Modules: one file per module, mod.rs only for re-exports
