Rust style guide

rust.md

@@ -0,0 +1,118 @@
+# Rust Guidelines
+This guide defines the core Rust conventions for our lab projects. It supplements the [official Rust style guide](https://doc.rust-lang.org/1.0.0/style/) with lab-specific practices for clarity and consistency.
+
+---
+
+## General Guidelines
+
+- Follow idiomatic Rust.
+- Prefer clarity over cleverness.
+- Use comments to explain *why*, not *what*.
+- Run `cargo fmt` before committing.
+
+---
+
+## Project Structure
+
+- Use `lib.rs` for libraries, `main.rs` for binaries.
+- Organize modules in separate files under `src/`.
+
+---
+
+## Formatting
+
+- Max line length: 100 chars.
+- Indent with 4 spaces (no tabs).
+- Run `cargo fmt` and `cargo clippy`.
+
+---
+
+## Naming Conventions
+
+| Item      | Style                 | Example         |
+|-----------|------------------------|-----------------|
+| Crates    | `snake_case`           | `my_crate`      |
+| Structs   | `CamelCase`            | `HttpRequest`   |
+| Enums     | `CamelCase`            | `ResponseCode`  |
+| Traits    | `CamelCase`            | `Serializable`  |
+| Consts    | `SCREAMING_SNAKE_CASE` | `MAX_RETRIES`   |
+| Vars/Fns  | `snake_case`           | `parse_header`  |
+
+---
+
+## Imports
+
+- Group: std → external → internal.
+- Alphabetize within groups.
+
+```rust
+use std::fs;
+use anyhow::Result;
+use crate::config::load;
+```
+
+---
+
+## Error Handling
+
+- Avoid `unwrap()` and `expect()`.
+- Using `Result<T, E>`; `anyhow::Result<T>` is acceptable for tools.
+
+---
+
+## Linting
+
+- Run `cargo clippy --all-targets --all-features`.
+- Fix all warnings unless there is a reason it should not be fixed.
+
+---
+
+## Testing
+
+- All public code should be tested.
+- Test both success cases and common failure cases.   
+- You do not need 100% test coverage except for in things like public APIs, but ~90% should be the norm.
+- Use `tests/` for integration tests.
+
+---
+
+## Benchmarking
+
+- Use the [`criterion`](https://crates.io/crates/criterion) crate for writing reliable benchmarks.  
+- Place benchmarks in the `benches/` directory using the standard Cargo bench layout.  
+- Group related benchmarks.
+- Run with `cargo bench` and use Criterion's statistical output to compare changes.  
+- Always benchmark in release mode (`--release`) for realistic results.
+
+---
+
+## Comments & Docs
+
+- Use `///` for public APIs, `//` for internal notes.
+- Avoid redundant comments.
+
+```rust
+/// Parses a user token from a header.
+fn parse_token(header: &str) -> Option<Token> {
+    // Strip "Bearer " prefix
+    header.strip_prefix("Bearer ").map(Token::from)
+}
+```
+
+---
+
+## TODOs
+
+- Use `// TODO(name):` format.
+
+```rust
+// TODO(user): handle invalid inputs
+```
+
+---
+
+## Pre-Commit Checklist
+
+- [ ] `cargo fmt`
+- [ ] `cargo clippy`
+- [ ] `cargo test`