Rust style guide

rust.md

@@ -0,0 +1,107 @@
+# 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()`.
+- Use `Result<T, E>`; `anyhow::Result<T>` is acceptable for tools.
+
+---
+
+## Linting
+
+- Run `cargo clippy --all-targets --all-features`.
+- Fix all warnings unless justified.
+
+---
+
+## Testing
+
+- All public code should be tested.
+- Use `#[cfg(test)] mod tests` for unit tests.
+- Use `tests/` for integration tests.
+
+---
+
+## 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`