# Rust Rules

## 🧱 Project Architecture

### **Modular Design**

* Organize code into **crates** and **modules**:

  * Use a **workspace** for multi-crate projects (`Cargo.toml` + `Cargo.lock` at root).
  * Split concerns into crates: e.g., `core`, `network`, `storage`, `cli`, `web`, `domain`, `infra`.
* Avoid monoliths — design for composability.

### **Layered Architecture**

Separate by **responsibility**, not technology:

* **Domain layer** – business logic, domain models, pure logic, no dependencies.
* **Application layer** – use-cases, orchestrators, service interfaces.
* **Infrastructure layer** – database, HTTP clients, FS, external APIs.
* **Presentation layer** – CLI, gRPC, REST API, etc.

Use traits to **abstract interfaces** between layers.

---

## 📦 Crate and Module Hygiene

### **Use Visibility Thoughtfully**

* Keep as much private (`pub(crate)` or private) as possible.
* Use `mod.rs` sparingly — prefer flat `mod_x.rs` and `mod x;` where possible.
* Keep `lib.rs` or `main.rs` minimal — just wiring and top-level declarations.

### **Predeclare your modules**

Explicitly declare modules in parent files, avoiding implicit module discovery:

```rust
mod domain;
mod services;
```

---

## 🧠 Code Design and Idioms

### **Prefer Composition Over Inheritance**

* Favor structs + traits over enums for extensibility.
* Use `impl Trait` for abstraction and `dyn Trait` for dynamic dispatch when needed.

### **Minimize Unnecessary Abstractions**

* Don't abstract over one implementation — wait for the second one.
* Don’t use traits where a simple function will do.

### **Idiomatic Error Handling**

* Use `Result<T, E>`, `?`, and `thiserror` or `anyhow` (depending on layer).
* Business logic: custom error enums (`thiserror`).
* App layer or CLI: use `anyhow::Result` for bubble-up and crash-on-error.

### **Zero-cost abstractions**

* Use generics, lifetimes, borrowing, and ownership where appropriate.
* Minimize heap allocations, unnecessary `.clone()`s.

## 🛠️ Tooling and Dev Experience

### **Use Clippy, Rustfmt, and IDEs**

* `clippy`: catch non-idiomatic code.
* `rustfmt`: consistent formatting.
* `cargo-expand`: inspect macro-generated code.

### **Use `cargo features` for Flexibility**

* Feature-gate optional deps and functionalities:

```toml
[features]
default = ["serde"]
cli = ["clap"]
```

## 🧪 Testing & Quality

### **Test by Layer**

* Unit tests for pure logic.
* Integration tests (`tests/`) for subsystems and public interfaces.
* End-to-end/system tests where applicable.

Use `mockall` or `double` for mocking when interface testing is needed.

### **Property-based test* Study open-source Rust projects like `ripgrep`, `tokio`, `tower`, `axum`, or `zellij`.

* Use `proptest` for verifying correctness over ranges of inputs.

## 📈 Performance and Safety

### **Measure Before Optimizing**

* Use `cargo bench`, `criterion`, `perf`, or `flamegraph` for real profiling.
* Don't optimize until there's a clear need.

### **Minimize Unsafe Code**

* Keep `unsafe` blocks minimal, justified, and well-documented.
* Use crates like `bytemuck`, `zeroize`, or `unsafe-libyaml` only when needed.

## 📚 Dependency Hygiene

### **Minimal and Audited Dependencies**

* Prefer well-maintained, minimal, audited crates.
* Avoid depending on "kitchen sink" crates unless unavoidable.
* Regularly check for security updates via `cargo audit`.

## 🧾 Documentation & Maintainability

### **Document Public APIs and Crates**

* Use `//!` and `///` comments.
* Auto-generate docs with `cargo doc --open`.

### **Conventional Naming**

* Stick to Rust conventions: `snake_case` for functions and variables, `PascalCase` for types.


### **Limit Shared Mutable State**

* Avoid global mutable state unless it’s guarded and justified.

### **Reproducible Builds**

* Pin versions where critical.
* Use lockfiles even in libraries (`[package] publish = false` in internal crates).

## 📁 Example Folder Structure

```text
my-app/
├── Cargo.toml
├── Cargo.lock
├── crates/
│   ├── core/
│   ├── api/
│   ├── domain/
│   └── storage/
├── bin/
│   └── cli.rs
├── tests/
│   └── integration.rs
├── docs/
│   └── architecture.md
```

## 🧭 Final Advice

* Think in **lifetimes**, **ownership**, and **borrowing**.
* Design for **testability** and **composability**.
* Don't fight the compiler — **embrace it as your co-architect**.
* Be conservative with third-party crates — **audit and isolate** them if needed.
* This project is pure Unix - do not make any Windows adjustments.