rust.md

Rust Guidelines

This guide defines the core Rust conventions for our lab projects. It supplements the official Rust style guide 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.

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.

/// 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.

// TODO(user): handle invalid inputs

---

Pre-Commit Checklist

• cargo fmt
• cargo clippy
• cargo test