1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
# 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`.
ing**
* 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.
## βοΈ Async, Concurrency, and IO
### **Choose Your Runtime Wisely**
* `tokio`: for production-grade, multi-core async workloads.
* `async-std`: if you prefer a more "standard" style.
* Use `tracing` instead of `log` for structured async-aware logging.
### **Limit Shared Mutable State**
* Prefer ownership and message passing (`tokio::sync::mpsc`, `crossbeam`, `flume`) over `Arc<Mutex<T>>`.
* 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.
|
