Back to Details

reflect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Reflect

反思

The first implementation is a draft. Now that the code exists, review and re-think whether it was done in the best way. Ask questions of the code and context. Act on improvements that do not depend on a product decision. Raise the rest.
Goal: a higher-quality first pass before the user looks in detail. This is not a code review. Formal review comes later.
"Best" means:
  • Simplest solution that solves the problem
  • The domain model is clearly expressed
  • Coherent and consistent with the existing codebase
  • Re-uses existing objects, helpers, conventions when appropriate
  • Isn't contorted around existing code that wasn't built with the new requirements in mind
  • Comments explain the intent and rationale for the code
  • Raises the average quality of the codebase, sets examples that others can follow
  • The right long-term architecture, not the smallest change
第一次实现只是草稿。现在代码已经存在，回顾并重新思考是否以最佳方式完成了需求。就代码和上下文提出疑问。对于不依赖产品决策的改进，直接落实；其余问题则予以提出。
目标：在用户细看之前交付质量更高的第一版。这不是代码评审，正式评审稍后进行。
“最佳”意味着：
  • 采用能够解决问题的最简单方案
  • 清晰表达领域模型
  • 与现有代码库保持连贯和一致
  • 在适当情况下复用现有对象、辅助函数和约定
  • 不会为了迁就最初并非针对新需求构建的现有代码而扭曲设计
  • 注释解释代码的意图和设计理由
  • 提升代码库的整体质量，并树立可供他人遵循的范例
  • 采用正确的长期架构，而不是追求最小改动

When to use

何时使用

  • The user says reflect, look again, second pass, shape this
  • Implicitly, after finishing a first implementation, including incremental changes to a WIP
  • Do not use during planning, while waiting on a design question, or as a substitute for a formal review
  • 用户要求反思、再看一遍、第二轮处理或梳理完善
  • 隐含适用于完成第一次实现之后，包括对 WIP 所做的增量更改
  • 不要在规划期间、等待设计问题答复时使用，也不要将其作为正式评审的替代品

Workflow

工作流

1. See the code

1. 查看代码

Re-read the change as if seeing it for the first time. Read the new/changed files and the surrounding modules they plug into. The goal is a high quality final shape, not the smallest diff.
像第一次看到代码一样重新阅读本次变更。阅读新增或修改的文件，以及它们所接入的周边模块。目标是形成高质量的最终形态，而不是最小的 diff。

2. Hunt and apply

2. 排查并应用

Work through the questions below. For each realization that does not depend on a product decision: do it. Do not ask permission to improve the code just written.
Leave it for the report when:
  • A requirement would be relaxed, changed, or dropped
  • Two product-valid paths exist and it is not obvious which is better
  • A product decision was taken silently during the build
  • A significant refactor to existing code is called for
逐项审视下列问题。每当发现一项不依赖产品决策的改进点，就直接执行。不要为了让刚写好的代码变得更好而请求许可。
以下情况留到报告中处理：
  • 某项需求需要放宽、修改或删除
  • 存在两条在产品层面都合理的路径，但无法明显判断哪一条更好
  • 构建过程中悄然作出了某项产品决策
  • 需要对现有代码进行重大重构

3. Repeat

3. 重复

Fresh problems and opportunities will appear with each iteration. Repeat the reflection and improvement process until it stabilizes, or you reach only product or design decisions that require the user's input.
每次迭代都会出现新的问题和改进机会。 重复反思和改进过程，直到结果趋于稳定，或者只剩下需要用户输入的产品或设计决策。

4. Report

4. 报告

Brief. What changed. Then leftover observations and decisions, numbered.
Wait for the user to respond.
简要说明。改了什么。然后按编号列出剩余观察和决策。
等待用户回应。

Questions

问题

Mostly, use your own judgement.
Now that you can see the code: was this the simplest and best way to address the need? Can it be simpler or more obvious?
Ask these of what you've just written:
  • Which requirements drove the complexity? Were any requirements interpreted too strictly? Which requirements were implicit? Challenge the user about them.
  • Now that you see the code, can it be rearranged to be more coherent?
  • What opportunities for simplification or improvement have emerged?
  • Are core concepts expressed just once, in a re-usable way?
  • Is anything awkward or surprising? Why?
  • Is the new code working around deficiencies in the codebase? Is there a straightforward fix?
  • What coupling emerged or was discovered? Is it justified?
  • Does this belong here, or should it pass through and live closer to where it's used?
  • Am I backing out or introspecting something that should have been constructed and passed through?
  • Can similar paths or structures be fruitfully unified?
  • Are there two different ways to do the same thing? Just pick one.
  • Is each piece of code in the right place?
  • Do we need this? Is it doing anything?
  • Are optional things truly optional?
  • What code smells are present?
  • Are names still appropriate, describing the now-current concepts?
  • What's the right architecture for this overall problem?
  • Would I actually build it this way if starting over?
  • Is this a hack?
主要依靠自己的判断。
现在你已经能够看到代码：这是解决该需求最简单且最佳的方式吗？能否变得更简单或更清晰？
针对刚写完的代码提出以下问题：
  • 哪些需求导致了复杂度？是否有任何需求被解读得过于严格？哪些需求是隐含的？就这些问题向用户提出质询。
  • 现在看到完整代码后，能否重新组织它，使其更加连贯？
  • 出现了哪些简化或改进机会？
  • 核心概念是否只表达了一次，并以可复用的方式呈现？
  • 是否有任何内容显得笨拙或令人意外？为什么？
  • 新代码是否在绕过代码库中的缺陷？是否存在直接且合理的修复方式？
  • 出现了或发现了哪些耦合？这些耦合是否合理？
  • 它应该属于这里，还是仅负责透传，并放在更靠近使用位置的地方？
  • 我是否在回退获取或直接内省某个本应构造后显式传入的东西？
  • 相似路径或结构能否进行有效统一？
  • 是否存在两种完成同一件事的不同方式？直接选择其中一种。
  • 每段代码是否都放在了正确的位置？
  • 我们真的需要它吗？它是否确实发挥着作用？
  • 可选内容是否真正可选？
  • 存在哪些代码坏味道？
  • 名称是否仍然合适，并能准确描述当前 concepts？
  • 针对这个整体问题，正确的架构是什么？
  • 如果从头开始，我是否真的会以这种方式构建它？
  • 这是否是一种 hack？

Silent product decisions

未确认的产品决策

Report these even when the code is fine. The user did not confirm them.
  • One of two user-visible behaviors was chosen
  • An application rule was encoded
  • A gate, cap, empty state, or copy path was invented
  • A default was picked that the user might want to see
即使代码本身没有问题，也要报告以下内容，因为用户并未确认这些决策。
  • 从两种用户可见行为中选择了其中一种
  • 对某项应用规则进行了编码
  • 自行设计了某种 gate、cap、empty state 或 copy path
  • 选择了某个用户可能希望看到的默认值

Do not

不要

  • Silently drop or loosen a requirement
  • Invent a base class or a prospective second caller
  • Rename a landed API field
  • Keep a workaround
  • Treat this as review-diff or a commit gate
  • 悄然删除或放宽需求
  • 凭空引入基类或预期的第二个调用方
  • 重命名已经落地的 API 字段
  • 保留权宜之计
  • 将此流程视为评审 diff 或提交门禁