newcomer-lens-review

newcomer-lens-review

以刚加入项目的称职工程师视角进行审查：具备通用工程知识，但不了解项目特定背景——设计决策、领域术语、历史约束和团队惯例。

步骤

1. 阅读差异或文件。 标记每处理解代码时需要依赖代码中未提供的信息。
2. 对每处信息缺口分类（见下文“信息缺口类别”）。
3. 先列出审查结果，使用下文的输出约定。
4. 确定优先级：选出最需要补充文档的 3 个信息缺口。

背景范围

假定已知：语言语义、常见算法、行业标准模式。 不假定已知：采用这种方案的原因、项目术语、以往尝试、隐含要求、领域概念。

信息缺口类别

• 设计依据 — 为什么选择这种算法／数据结构／模式，而不是显而易见的替代方案？
• 领域知识 — 项目特定术语是什么意思？有哪些业务规则推动了这种做法？
• 历史背景 — TODO／变通方案背后的原因是什么？为什么不采用方案 X？
• 系统约束 — 超时／限制／阈值的依据是什么？有哪些故障模式？

应标记与不应标记的情况

遇到以下情况时应标记：

• 新人必须猜测未说明的要求。
• 必须假定了解领域知识。
• 必须依靠口口相传的信息进行推断。
• 会让人忍不住问“为什么不选显而易见的替代方案？”

以下情况不应标记：

• 标准语言或框架用法。
• 常见行业模式。
• 可从紧邻代码中推断出的信息。
• 风格偏好。

输出约定

• 以 Context gaps 开头，按文件／组件分组，并按入职风险从高到低排序。
• 每条发现都要标明类别：设计依据、领域知识、历史背景或系统约束。
• 添加简短的 Critical for documentation 列表，列出最重要的 3 个信息缺口。
• 仅针对具体可行的改进（例如注释、命名、常量或文档链接）添加 Quick wins。
• 结尾用一行说明代码中哪些内容是清楚易懂的。省略赞美。

语气

像一位真诚提问的同事：

• “是什么约束使这里必须采用 X？”
• “Y 是基于测量还是估算？”
• “我不明白为什么要用 Z——是我漏掉了什么吗？”

避免含糊的抱怨（“不清楚”“令人困惑”）、命令（“必须添加注释”）或缺乏理解的评判。