refining

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Refining

代码变更优化

Refine code changes to make them easy to review.

优化代码变更，使其更易于评审。

Philosophy

核心理念

Why Refine?

为何需要优化？

Refining exists because reviewers are humans with limited attention.

The core question isn't "what checks should I run?" but "would I want to review this?"

The Reviewer's Reality:
├── Context loading takes mental effort
├── Large changes exhaust attention
├── Mixed concerns require mental switching
└── Unclear changes create uncertainty

代码变更优化的存在是因为评审者是注意力有限的普通人。

核心问题不是“我应该运行哪些检查？”，而是“我愿意评审这样的代码变更吗？”

评审者的实际处境:
├── 加载上下文需要耗费脑力
├── 大规模变更会耗尽注意力
├── 混合关注点需要频繁切换思维
└── 模糊的变更会带来不确定性

The Reviewer's Burden

评审者的负担

Every code review requires:

Context loading - Understanding what the change is about
Verification - Checking if it's correct
Risk assessment - What could this break?

Small, focused changes make this tractable. Large, mixed changes make it exhausting.

每一次代码评审都需要：

上下文加载 - 理解变更的核心内容
验证 - 检查变更是否正确
风险评估 - 变更可能会破坏哪些内容？

小而聚焦的变更让评审变得可控，大而杂乱的变更则会让评审疲惫不堪。

Cohesion Over Size

内聚性优先于规模

A 500-line focused change is often easier to review than a 200-line mixed change.

Why?

Focused changes have one mental model
Mixed changes require context switching for each concern
Each concern should be independently verifiable

The "lines changed" heuristic is about cognitive load, not absolute limits. Ask: Could a reviewer hold this entire change in their head?

一个500行的聚焦型变更通常比200行的混合型变更更易于评审。

为什么？

聚焦型变更只需要一种思维模型
混合型变更需要针对每个关注点切换上下文
每个关注点都应该可以独立验证

“变更行数”的判断标准是认知负荷，而非绝对数值。请自问：评审者能否将整个变更的内容记在脑子里？

The Refining Mindset

优化思维模式

Before committing or creating a PR, ask:

Would I want to review this?
Can I explain this in one sentence?
If this breaks, is the blast radius obvious?

If yes to all → proceed. If no → refine further.

在提交代码或创建PR之前，请自问：

我愿意评审这样的变更吗？
我能用一句话解释清楚这个变更吗？
如果这个变更出问题，影响范围是否清晰？

如果全部回答“是” → 继续执行。如果有“否” → 进一步优化。

Core Concepts

核心概念

Reviewability Factors

可评审性因素

Factor	What it measures	Why it matters
Cohesion	Single purpose?	Mental model simplicity
Size	Cognitive load	Reviewer attention span
Clarity	Is intent obvious?	Time to understand
Noise	Distractions present?	Focus degradation

These aren't gates to pass. They're lenses to evaluate through.

因素	衡量标准	重要性
内聚性	是否单一目标？	思维模型简洁性
规模	认知负荷大小	评审者注意力持续时间
清晰度	变更意图是否明确？	理解所需时间
干扰项	是否存在无关内容？	注意力分散程度

这些不是必须通过的关卡，而是用于评估的视角。

When to Split

何时拆分变更

Not "must split" - but "consider splitting":

Feature + refactor → Refactor can be reviewed independently
Bug fix + new feature → Fix is urgent, feature can wait
Multiple unrelated changes → Each deserves its own commit

The question: Would reviewing these separately produce better feedback?

不是“必须拆分”，而是“考虑拆分”的场景：

功能开发 + 代码重构 → 重构可以独立评审
Bug修复 + 新功能开发 → 修复是紧急需求，功能可以延后
多个无关变更 → 每个变更都应有独立的提交

判断标准：分开评审这些变更是否能得到更优质的反馈？

Noise Detection

干扰项检测

Noise makes reviewers work harder without adding value:

```
console.log
```
,
```
print
```
,
```
debugger
```
→ Should these be here?
```
TODO
```
/
```
FIXME
```
in new code → Is this intentional?
Commented-out code → Dead code or notes?

Note these to the user. Let them decide if intentional.

干扰项会让评审者付出更多努力却没有价值：

```
console.log
```
,
```
print
```
,
```
debugger
```
→ 这些是否应该保留？
新代码中的
```
TODO
```
/
```
FIXME
```
→ 这是有意为之吗？
被注释掉的代码 → 是废弃代码还是备注？

将这些情况告知用户，由他们决定是否保留。

Three Modes

三种模式

Commit

提交模式

Validate staged changes, create commit.

1. Check staged:     git diff --cached --stat
2. Assess:           Cohesion? Size? Noise?
3. Generate message: Conventional Commits format
4. Commit:           git commit -m "type(scope): description"

Never push unless explicitly requested.

验证暂存的变更，创建提交记录。

1. 检查暂存内容:     git diff --cached --stat
2. 评估变更:           内聚性？规模？干扰项？
3. 生成提交信息:  遵循Conventional Commits格式
4. 提交代码:           git commit -m "type(scope): description"

除非明确要求，否则不要推送代码。

Review

评审模式

Assess a PR/MR or branch comparison.

1. Identify target:  PR URL, branch, or current changes
2. Quick assessment: Cohesion, size, obvious issues
3. Detailed review:  Focus on what linters miss
4. Report:           Severity-based (🔴 Critical, 🟡 Important, 🔵 Suggestion)

Focus your attention where it matters most. Skip what automated tools catch.

See reference/review-strategies.md for project-specific approaches.

评估PR/MR或分支对比结果。

1. 确定目标:  PR链接、分支或当前变更
2. 快速评估:  内聚性、规模、明显问题
3. 详细评审:  聚焦于静态检查工具未覆盖的内容
4. 生成报告:  基于严重程度分类（🔴 关键问题，🟡 重要问题，🔵 建议）

将注意力集中在最关键的地方，跳过自动化工具能检测到的内容。

查看reference/review-strategies.md获取项目特定的评审方法。

Create PR/MR

创建PR/MR模式

Generate reviewer-focused description.

1. Gather changes:   git log --oneline main..HEAD
2. Assess:           Is this PR-ready?
3. Generate:         Title + description + context
4. Create:           gh pr create / glab mr create

Description structure:

markdown

undefined

生成以评审者为中心的描述。

1. 收集变更记录:   git log --oneline main..HEAD
2. 评估就绪度:           这个变更是否适合创建PR？
3. 生成内容:         标题 + 描述 + 上下文
4. 创建PR/MR:           gh pr create / glab mr create

描述结构:

markdown

undefined

Summary

摘要

[What and why in 1-2 sentences]

[用1-2句话说明变更内容和原因]

Changes

变更详情

[Key changes as bullet points]

[用 bullet 点列出关键变更]

Testing

测试方式

[How to verify this works]

[如何验证变更有效]

Reviewer Notes

评审提示

[What to focus on, known risks, trade-offs]


See [reference/description-guide.md](reference/description-guide.md) for examples.

[需要重点关注的内容、已知风险、权衡方案]


查看[reference/description-guide.md](reference/description-guide.md)获取示例。

Understanding, Not Rules

理解而非刻板遵循规则

Instead of memorizing thresholds, understand the underlying tensions:

Tension	Resolution
Speed vs Quality	Quick changes need less refinement. Critical paths need more.
Completeness vs Focus	Better to have multiple focused PRs than one sprawling one.
Description Detail vs Reader Time	Enough to understand, not encyclopedic.
Stopping Early vs Proceeding	When in doubt, ask. User decides.

不要死记硬背阈值，而是理解背后的权衡：

权衡点	解决方案
速度 vs 质量	快速变更需要的优化更少，关键路径需要更多优化
完整性 vs 聚焦性	多个聚焦的PR比一个庞大的PR更好
描述详细程度 vs 读者时间	足够理解即可，无需面面俱到
提前停止 vs 继续优化	存疑时询问用户，由他们决定

On Line Counts

关于变更行数

"400 lines" isn't a magic number. It's a heuristic for "about the limit of focused review."

Simple rename across many files? 1000 lines might be fine.
Complex algorithm change? 100 lines needs careful review.

Match review depth to change complexity, not line count.

“400行”不是魔法数字，它只是“聚焦评审的大致上限”的参考值。

简单的跨文件重命名？1000行可能也没问题。
复杂的算法变更？100行也需要仔细评审。

根据变更复杂度匹配评审深度，而非行数。

Reference

参考资料

Load these as needed, not upfront:

reference/reviewability.md - Detailed criteria
reference/description-guide.md - PR/MR examples
reference/review-strategies.md - Approaches by context
reference/review-checklist.md - Language-specific checks
reference/impact-analysis.md - Blast radius techniques

按需查看以下资料，无需预先通读：

reference/reviewability.md - 详细的可评审性标准
reference/description-guide.md - PR/MR描述示例
reference/review-strategies.md - 场景化评审方法
reference/review-checklist.md - 语言特定的检查清单
reference/impact-analysis.md - 影响范围分析技巧

The Goal

目标

The goal isn't to follow a checklist. It's to create changes that reviewers can understand quickly and review confidently.

Reviewability is empathy. Put yourself in the reviewer's shoes.

我们的目标不是遵循检查清单，而是创建评审者能快速理解并自信评审的代码变更。

可评审性本质是同理心——站在评审者的角度思考。