程序员英语 06：代码评审与技术说明

一句 This is wrong. 表达了否定，却没有让作者知道哪里错、何时错、应该检查什么。技术协作中的英语应把判断转化为可讨论的证据。

评审意见的三部分

假设代码取列表的第一个元素，没有检查空列表。可以写：

If the input list is empty, this access fails before validation runs. Could we check the length first and add an empty-input case?

第一部分是触发条件，第二部分是后果，第三部分是建议与验证。评论指向代码行为，无需评价作者能力。

Google 代码评审指南 强调礼貌、解释理由和关注代码。落到日常写作，可以给不同性质的意见加上明确提示：

性质	示例
阻止合并的问题	Blocking: This can discard unsaved edits when the user cancels.
需要澄清	Question: Is the input guaranteed to be sorted here?
改进建议	Suggestion: Naming this value timeoutMs would make the unit clearer.
轻微风格意见	Nit: Consider using the existing term “record” for consistency.

这些标签是表达方法，不是通用强制标准。团队有约定时按约定使用；不能把数据丢失问题写成 Nit 来弱化风险。

回复时说明处理结果

仅回 Done，评审者仍要重新查找修改。更具体的回复是：

Added the empty-input check before indexing the list.
The new test covers an empty list and confirms that validation returns an error.

不同意建议时也先说明约束：Sorting here would change the output order required by the file format. Could we keep the original order and validate it instead? 这比 I don't agree 多提供了一个可核对的理由。所说的格式要求必须确有依据。

技术说明：先写读者需要的结论

想解释一个导出流程，不必从内部类名讲起。可以按“行为、原因、边界、验证”组织：

The exporter writes to a temporary file before replacing the target.
This keeps an incomplete export from being mistaken for a finished report.
We still need to verify the replacement behavior on each supported platform.
The current test covers an interrupted write before the replacement step.

说明把已知结果与未验证边界分开。不要据此声称任何平台、任何文件系统上替换都具备相同保证。

删除空泛的引导语也能让句子更清晰：把 It is important to note that the cache is cleared when the file changes. 简化成 The cache is cleared when the file changes.。主语明确时也可写 The watcher clears the cache when the file changes.；不知道执行者时，保留被动语态比编造主语准确。

练习：修改评审语气与信息量

原意见：Why didn't you think about concurrency? This is bad.

已知：两个线程可能同时读到计数 9，再各自写入 10，预期最终应为 11。写一条可操作的英文评审意见。再把 It is very obvious that this implementation is much better. 改成一个需要证据的具体说明。

查看答案与讲解

评审意见：If two threads read the same counter value, one update can overwrite the other. Could we protect the read-modify-write operation and add a concurrent-update test?

技术说明可以写：This implementation performs one file scan instead of two. We still need a benchmark to compare the total runtime.

第二句是一个写法示例，只有实际从两次扫描变成一次时才能使用。删除 obvious 和 better，用可核对的变化替代；运行次数减少也不直接等于总耗时减半。

资料与延伸

Google 文档语气指南 可作为改稿参考。练习时读出自己的评论，检查是否缺少条件、是否把猜测写成事实、是否让对方知道下一步。