write-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write Code

编写代码

Rust code conventions for Syncpack.

Syncpack的Rust代码规范

Style

风格

Functional style: pipelines over loops
Avoid
?
chains: use
```
.and_then()
```
,
```
.map()
```
,
```
.or_else()
```
Descriptive names: clarity over brevity
Named placeholders:
```
println!("{var}")
```
not
```
println!("{}", var)
```
British English: "behaviour" not "behavior", "organised" not "organized"

函数式风格： 使用管道操作而非循环
避免
?
链式调用：改用
```
.and_then()
```
、
```
.map()
```
、
```
.or_else()
```
描述性命名： 清晰优先于简洁
命名占位符： 使用
```
println!("{var}")
```
而非
```
println!("{}", var)
```
英式英语拼写： 使用“behaviour”而非“behavior”，“organised”而非“organized”

Imports

导入

Single

use

statement with grouped braces:

rust

use {
  crate::{cli::Cli, config::Config},
  log::{debug, error},
  std::{process::exit, sync::Arc},
};

Rules:

Never use
super::
— always
```
crate::
```
for internal imports
Group:
```
crate::
```
, external crates,
```
std::
```
Alphabetise within groups

使用单个

use

语句并通过大括号分组：

rust

use {
  crate::{cli::Cli, config::Config},
  log::{debug, error},
  std::{process::exit, sync::Arc},
};

规则：

绝不使用
super::
—— 内部导入始终使用
```
crate::
```
分组顺序：
```
crate::
```
、外部crate、
```
std::
```
组内按字母顺序排序

File Organisation

文件组织

Adding...	Location
New command	`src/commands/{name}.rs`
New test	Sibling `_test.rs` file (e.g., `src/foo.rs` → `src/foo_test.rs` )

NEVER use

#[cfg(test)]

modules inside implementation files.

新增内容	位置
新命令	`src/commands/{name}.rs`
新测试	同目录下的 `_test.rs` 文件（例如： `src/foo.rs` → `src/foo_test.rs` ）

绝不在实现文件内使用

#[cfg(test)]

模块。

Quality

质量

Functions <50 lines, commands 100-300 lines
Zero warnings (except during TDD red phase)
No comments by default (only for genuinely complex logic)
Run
```
just format
```
before committing

函数长度<50行，命令代码长度100-300行
零警告（TDD红阶段除外）
默认不写注释（仅针对真正复杂的逻辑添加）
提交前运行
```
just format
```

Patterns

模式

Iterating Instances

实例迭代

rust

ctx.version_groups.iter().for_each(|group| {
    group.get_sorted_dependencies(&ctx.config.cli.sort).for_each(|dependency| {
        dependency.get_sorted_instances()
            .filter(|instance| instance.is_invalid())
            .for_each(|instance| { /* process */ });
    });
});

rust

ctx.version_groups.iter().for_each(|group| {
    group.get_sorted_dependencies(&ctx.config.cli.sort).for_each(|dependency| {
        dependency.get_sorted_instances()
            .filter(|instance| instance.is_invalid())
            .for_each(|instance| { /* 处理逻辑 */ });
    });
});

Error Handling

错误处理

Prefer combinators over

rust

// Good
path.parent()
    .and_then(|p| p.to_str())
    .map(|s| s.to_string())
    .unwrap_or_default()

// Avoid
let parent = path.parent()?;
let str = parent.to_str()?;
Ok(str.to_string())

优先使用组合子而非

：

rust

// 推荐写法
path.parent()
    .and_then(|p| p.to_str())
    .map(|s| s.to_string())
    .unwrap_or_default()

// 避免写法
let parent = path.parent()?;
let str = parent.to_str()?;
Ok(str.to_string())

State Mutation

状态变更

rust

let mut state = instance.state.borrow_mut();
if !state.is_invalid() {
    *state = InstanceState::fixable(SomeVariant);
}

rust

let mut state = instance.state.borrow_mut();
if !state.is_invalid() {
    *state = InstanceState::fixable(SomeVariant);
}