coding-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rust Coding Guidelines (50 Core Rules)

Rust编码指南（50条核心规则）

Naming (Rust-Specific)

命名（Rust专属）

Rule	Guideline
No `get_` prefix	`fn name()` not `fn get_name()`
Iterator convention	`iter()` / `iter_mut()` / `into_iter()`
Conversion naming	`as_` (cheap &), `to_` (expensive), `into_` (ownership)
Static var prefix	`G_CONFIG` for `static` , no prefix for `const`

规则	指南
不要使用 `get_` 前缀	使用 `fn name()` 而非 `fn get_name()`
迭代器约定	`iter()` / `iter_mut()` / `into_iter()`
转换命名	`as_` （低成本引用）、 `to_` （高成本转换）、 `into_` （所有权转移）
静态变量前缀	`static` 类型使用 `G_CONFIG` ， `const` 类型无需前缀

Data Types

数据类型

Rule	Guideline
Use newtypes	`struct Email(String)` for domain semantics
Prefer slice patterns	`if let [first, .., last] = slice`
Pre-allocate	`Vec::with_capacity()` , `String::with_capacity()`
Avoid Vec abuse	Use arrays for fixed sizes

规则	指南
使用新类型	用 `struct Email(String)` 实现领域语义
优先使用切片模式	`if let [first, .., last] = slice`
预分配内存	`Vec::with_capacity()` 、 `String::with_capacity()`
避免滥用Vec	固定大小场景使用数组

Strings

字符串

Rule	Guideline
Prefer bytes	`s.bytes()` over `s.chars()` when ASCII
Use `Cow<str>`	When might modify borrowed data
Use `format!`	Over string concatenation with `+`
Avoid nested iteration	`contains()` on string is O(n*m)

规则	指南
优先使用字节	处理ASCII时用 `s.bytes()` 而非 `s.chars()`
使用 `Cow<str>`	可能修改借用数据时使用
使用 `format!`	替代 `+` 进行字符串拼接
避免嵌套迭代	字符串的 `contains()` 是O(n*m)复杂度

Error Handling

错误处理

Rule	Guideline
Use `?` propagation	Not `try!()` macro
`expect()` over `unwrap()`	When value guaranteed
Assertions for invariants	`assert!` at function entry

规则	指南
使用 `?` 进行错误传播	而非 `try!()` 宏
优先使用 `expect()` 而非 `unwrap()`	当值有保证时使用
用断言维护不变量	在函数入口处使用 `assert!`

Memory

内存

Rule	Guideline
Meaningful lifetimes	`'src` , `'ctx` not just `'a`
`try_borrow()` for RefCell	Avoid panic
Shadowing for transformation	`let x = x.parse()?`

规则	指南
有意义的生命周期	使用 `'src` 、 `'ctx` 而非仅 `'a`
对RefCell使用 `try_borrow()`	避免恐慌
用变量遮蔽实现转换	`let x = x.parse()?`

Concurrency

并发

Rule	Guideline
Identify lock ordering	Prevent deadlocks
Atomics for primitives	Not Mutex for bool/usize
Choose memory order carefully	Relaxed/Acquire/Release/SeqCst

规则	指南
明确锁的顺序	防止死锁
原类型使用原子操作	布尔/无符号整数类型不要用Mutex
谨慎选择内存顺序	Relaxed/Acquire/Release/SeqCst

Async

异步

Rule	Guideline
Sync for CPU-bound	Async is for I/O
Don't hold locks across await	Use scoped guards

规则	指南
CPU密集型任务用同步	异步适用于I/O密集型任务
不要在await期间持有锁	使用作用域守卫

Macros

宏

Rule	Guideline
Avoid unless necessary	Prefer functions/generics
Follow Rust syntax	Macro input should look like Rust

规则	指南
非必要不使用	优先选择函数/泛型
遵循Rust语法	宏输入应符合Rust语法风格

Deprecated → Better

已废弃 → 更优方案

Deprecated	Better	Since
`lazy_static!`	`std::sync::OnceLock`	1.70
`once_cell::Lazy`	`std::sync::LazyLock`	1.80
`std::sync::mpsc`	`crossbeam::channel`	-
`std::sync::Mutex`	`parking_lot::Mutex`	-
`failure` / `error-chain`	`thiserror` / `anyhow`	-
`try!()`	`?` operator	2018

已废弃	更优方案	起始版本
`lazy_static!`	`std::sync::OnceLock`	1.70
`once_cell::Lazy`	`std::sync::LazyLock`	1.80
`std::sync::mpsc`	`crossbeam::channel`	-
`std::sync::Mutex`	`parking_lot::Mutex`	-
`failure` / `error-chain`	`thiserror` / `anyhow`	-
`try!()`	`?` 操作符	2018

Quick Reference

快速参考

Naming: snake_case (fn/var), CamelCase (type), SCREAMING_CASE (const)
Format: rustfmt (just use it)
Docs: /// for public items, //! for module docs
Lint: #![warn(clippy::all)]

Claude knows Rust conventions well. These are the non-obvious Rust-specific rules.

Naming: snake_case (fn/var), CamelCase (type), SCREAMING_CASE (const)
Format: rustfmt (just use it)
Docs: /// for public items, //! for module docs
Lint: #![warn(clippy::all)]

Claude精通Rust约定。以上是一些非显而易见的Rust专属规则。