技术英语 / 系统课时
写清预期结果与实际结果
写清预期结果与实际结果
Issue 中最重要的差异不是“我认为哪里坏了”,而是相同操作下本来应该发生什么与实际发生了什么。把 expected behavior 和 actual behavior 分开写,并附上可观察证据,可以让维护者先确认事实,再判断真正的根因。
学习目标
- 能分别写清 expected behavior 和 actual behavior
- 能使用日志、错误信息和可观察结果支撑实际现象
- 能避免把未经验证的原因猜测写成确定事实
预期结果要描述可观察行为
Expected behavior 应回答:“按照文档、接口约定或正常行为,完成上述步骤后应该看到什么?”重点是外部可观察结果,而不是笼统评价。
例如,The command should work. 信息太少,因为“work”无法验证。更清楚的写法是:The command should exit with status 0 and create an output file named result.json.。维护者据此可以判断输出文件和退出状态是否符合预期。
如果预期来自官方文档、已有测试或稳定版本,可以简要说明依据;如果只是自己的产品需求,不要把它包装成项目已经承诺的行为。
实际结果只陈述已经观察到的事实
Actual behavior 应描述执行同样步骤后真正出现的结果,包括错误信息、退出状态、页面表现、缺失的文件或其他稳定可观察现象。不要一开始就写“这是因为缓存失效”或“线程竞争导致了异常”,除非已经有足够证据证明根因。
下面是一段适合放进 Issue 的实际结果示例:
The command exits with status 1.
No `result.json` file is created.
The terminal prints:
TypeError: Cannot read properties of undefined (reading 'name')这里记录的是退出状态、文件是否生成和原始错误信息。维护者可以验证这些事实,即使最后发现异常根因与你最初的猜测完全不同,Issue 仍然有价值。
用成对描述突出真正的差异
Expected 和 actual 最好描述同一个观察点,否则读者还需要自己推导差异。例如预期部分谈返回值,实际部分却只说 CPU 升高,就很难判断两者是否是同一问题。
可以按下面的方式组织:
### Expected behavior
The request should return HTTP 200 with the parsed document.
### Actual behavior
The request returns HTTP 500 instead. The response body is:
`{"error":"unexpected token"}`这是 Issue 文本的片段示例。它把比较对象固定为同一次请求的 HTTP 状态和响应,因此维护者一眼就能看出偏差在哪里。
如果差异涉及时间,也要给出足够具体的观察方式。例如不要只写“很慢”,而可以写“正常约 300 ms,本次连续五次均超过 8 s”。如果数字受机器性能影响,应明确它是观察值,而不是项目承诺的性能指标。
把推测与证据明确分开
提交者当然可以提供自己的调查结果,但应把事实与推测分开。The crash happens after the cache is cleared. 是观察;The cache implementation is broken. 则已经是原因判断。前者可以直接放在 actual behavior,后者更适合写成带保留语气的补充信息。
英语中可以使用 This may be related to...、I suspect... 或 I have not confirmed whether... 表达尚未验证的判断。这样既能给维护者提供排查线索,又不会把讨论锁死在错误方向上。
提交前只需要检查一件事:陌生维护者能否仅凭 expected 和 actual 两段,准确说出“哪里与预期不同”。如果答案是肯定的,再加上原始日志或错误信息作为证据,这个 Issue 就已经建立了清晰、可验证的事实基础。