技术英语 / 系统课时

写清预期结果与实际结果

写清预期结果与实际结果

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 的实际结果示例:

text
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 升高,就很难判断两者是否是同一问题。

可以按下面的方式组织:

markdown
### 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 就已经建立了清晰、可验证的事实基础。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

写清预期结果与实际结果

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通