好的代码评审,让新 FDE 一周比一周更少依赖你
每条评论标明是否阻塞、写清理由、让作者自己选改法:客户有保障,新人也成长得更快。
要点速览
- 评审有一个次要但重要的目标:让作者随着时间推移需要的评审越来越少。
- 阻塞、非阻塞和 nit 三种标签,让新 FDE 一眼看出代码接触客户数据之前哪些必须改。
- 说清问题和理由,让作者决定怎么改,代码确实变好时就批准。
一名新 FDE 入职三周,提交了第一个接触真实客户数据的拉取请求(PR):一个把订单从客户 API 同步到数据仓库的脚本。打开一看,你想评论的地方有 14 处。客户周一上午就要试运行。这是一个假设的场景,但并不陌生。
常见的捷径有两条。一是为了省时间自己重写,结果下次新人还得等你。二是留下 14 条看起来同样严重的评论,新人花两天从变量名改到一个可能弄乱客户数据的 bug,却不知道哪些真正要紧。
对前线部署工程师(FDE)来说,评审既是代码在客户环境运行前的最后一道防线,也是每天都在运转的培训渠道。所以评论怎么写,直接影响新人多快能独立工作,也是你带人能力的一个直观信号。
衡量标准:他们还有多需要你
Google 的代码评审指南明确写了一个次要目标:提升作者的能力,让他们随着时间推移需要的评审越来越少。换句话说,好的评审不只看抓到了多少缺陷,还要看同一个人的下一个 PR 里需要阻塞的地方是否变少了。
这个目标与 FDE 团队带新人的方式相符。根据 FDE Academy 对入职前 90 天的描述,早期工作会被圈定在一定范围内,让新人在风险仍可控的地方犯错,而不是在旗舰客户身上犯错。
经理会保持密切指导,但不至于让人窒息。里程碑是新人可以在没有严密监督的情况下接手一个真实项目的那一刻。
“密切但不窒息”的指导,正是在评审中发生的。矛盾在于:客户需要安心,新人需要自己做决定的空间。解法是把两件事分开:哪些问题会给客户带来风险、因此要阻止合并,哪些只是经验分享。
一个 PR,三类评论
回到订单同步脚本。假设核心代码如下:
def sync_orders(since):
orders = client.get("/orders", params={"since": since}).json()
for o in orders:
log.info(f"正在同步 {o}")
db.execute(
"INSERT INTO orders VALUES (%s, %s, %s)",
(o["id"], o["email"], o["total"]),
)
这段代码在演示中能跑通,但有两个会伤害客户的缺陷、一个待确认的问题,以及几处纯粹的外观问题。一组好的评论会把每一类都标得清清楚楚:
issue (blocking):如果网络故障后任务重跑,这条 INSERT 会写入重复订单,
客户看板上的收入会被算两次。需要一种无论执行多少次结果都相同的写法。
具体用哪种方案,由你决定。
issue (blocking):这行日志打印了整个订单,包括终端客户的邮箱。
日志的读者,无论是人还是系统,通常都比数据库多。只记录订单 id 即可。
question (non-blocking):客户的 API 有分页吗?如果有,这个函数可能
只拿到了第一页。
nit:把 `o` 改名为 `order`,可读性更好。可改可不改。
“blocking”(阻塞)和“non-blocking”(非阻塞)标签来自 Conventional Comments。这套约定把阻塞评论定义为:问题解决之前 PR 不能被接受。
约定的作者认为,加标签能为评审者和作者省下数小时的误解。“Nit”前缀则来自 Google,指技术上应该处理、但影响不大的小问题。
措辞上还有三个细节值得注意。每条评论都针对代码(“这条 INSERT 会写入重复订单”),而不是针对人(“你忘了处理重跑”),这符合 Google 的原则:评论代码,永远不评论作者。
每条评论都附有一句理由,因为理由能帮作者理解你为什么提出这一点,并把背后的原则带到下一个 PR。
第三个细节更微妙。对重复写入的 bug,你指出问题,让作者自己选改法;按 Google 的说法,这样做通常能让作者学到更多。
对日志里的邮箱,你直接给出改法,因为正确答案只有一个,客户数据也不是做实验的地方。知道什么时候让新人自己想、什么时候直接指路,是带人最难的部分。
什么时候点批准
现在重新数一遍最初的 14 处。假设分类之后有 2 个阻塞问题、3 个问题或建议、9 个 nit。新人一个下午改完 2 个阻塞问题,回答了 3 个问题,PR 在周末前合并;9 个 nit 放进之后的清理 PR。
这正是 Google 推荐的批准标准:只要变更确实改善了代码库的整体健康度,即使不完美,也倾向于批准。
评审者追求的是持续改进,而不是完美。对 FDE 来说,这个标准还有一层含义:客户恰好在风险所在之处得到保护,新人也不会在无关紧要的地方被卡住。
同一个 bug,因人而异的剂量
Crafting Tech Teams 上的文章《Benevolent Code Reviews As a Busy Manager》建议,根据提交 PR 的个人或结对搭档调整语言和详细程度。
对入职第一周的新人,关于重复写入的评论可能要写三句话,再附一个任务重跑的例子。到第六周,同样的问题只需一句提问:“如果跑两次会怎样?”
这句简短的提问是进步的标志,而不是偷懒。你正在把判断力从自己脑中转移到新人脑中。
同一篇文章强调,评审应当起到教育、支持和扫清障碍的作用,人在感到被评判时学不进东西。客户截止日期前的一连串严厉评论,最容易让新人不再提问。
下一个 PR 的五个步骤
第 1 步:识别风险。 读第一行代码之前,先问这个 PR 在客户侧接触了什么:真实数据、个人信息,还是只是内部工具。答案决定了阻塞门槛放在哪里。
第 2 步:先读完再写。 评论之前先把整个 PR 过一遍,这样才能按严重程度排序,而不是按代码行的顺序评论。
第 3 步:每条评论套用模板。 每条评论都有标签、针对代码、附一句理由;只有对客户风险高时才直接给出改法。
第 4 步:尽早批准。 阻塞点一解决就点批准,把 nit 推到清理 PR。
第 5 步:跟踪趋势。 记录你所带的人每个 PR 上的阻塞评论数量;如果这个数字逐周下降,说明你做对了。
评审者的常见错误
最常见的错误是替他们改。今天快了,整个季度却慢了,因为新人从没自己走一遍推理过程。第二个是所有评论都不加标签,作者把变量名和数据丢失 bug 一视同仁。
第三个出现在客户压力下:出于焦虑把 nit 升级成阻塞,或者反过来,为了赶演示把安全 bug 降级为非阻塞。最后一个是对所有人用同一种详细程度,对已经有把握的人啰嗦,对新人却过于简略。
FDE Academy 描述的 90 天里程碑,即新人可以在没有严密监督的情况下接手真实项目,如果你的目标是高级 FDE 或 FDE 负责人岗位,这也是值得写进简历的成果。要写具体:你把谁带到了这个里程碑,为团队引入了哪些评审约定来帮助他们做到。
面试时,拿出一条你写过的、带标签和理由的真实评论,通常比泛泛描述自己的领导力更有说服力。
好的导师衡量成功的方式有些反直觉:有一天,新人的 PR 到了你手上,已经没有什么需要阻塞的了。
这篇文章对你有帮助吗?
感谢你的反馈!