rust general

Rust General Rules

Project Structure

• Keep crates focused and name modules by domain responsibility.
• Put reusable library code in src/lib.rs and binary entry points in src/main.rs or src/bin/.
• Keep public APIs small and documented.
• Use feature flags deliberately and document non-default features.
• Commit Cargo.lock for applications; follow the project convention for libraries.

Ownership and Types

• Prefer borrowing over cloning when ownership is not needed.
• Use owned values at API boundaries when the callee must store data.
• Model domain states with enums and structs instead of strings or booleans.
• Use Option<T> for absence and Result<T, E> for fallible operations.
• Avoid unwrap() and expect() outside tests, examples, and process-startup invariants.

Error Handling

• Use thiserror or project-standard custom errors for libraries.
• Use anyhow or project-standard context-rich errors for applications.
• Add context when crossing IO, network, database, or parsing boundaries.
• Do not discard errors with _ unless explicitly documented.

Concurrency and Async

• Use Send and Sync boundaries intentionally.
• Prefer message passing or owned task inputs for async work.
• Do not hold blocking locks across .await.
• Use tokio::task::spawn_blocking or equivalent for blocking CPU or IO in async applications.
• Propagate cancellation through futures rather than hiding it in detached tasks.

Testing and Quality

• Run cargo fmt and cargo clippy before delivery.
• Add unit tests for pure logic and integration tests for public behavior.
• Use property tests for parsers, serializers, and state machines when useful.
• Use benchmarks only after identifying a real performance question.

Common Mistakes

• Do not fight the borrow checker by adding unnecessary Arc<Mutex<_>>.
• Do not expose internal module structure through public APIs by accident.
• Do not allocate in hot loops without measuring.
• Do not use unsafe code unless the invariant is documented and tested.