(翻译)编写有效的bug report

--- 原著 Elisabeth Hendrickson 《 Writing Effective Bug Reports 》

---Kiki 翻译于 2005/6/2

 

        你有没有为了要更多的信息而被返回 bug report 的经历呢？有没有碰到过你发现的一个非常严重的错误被推迟到下一个版本才去修复的情况呢？

 

      你提交的每一个bug report都是和项目组就正在测试中的软件质量问题的一种书面沟通方式。通常，你用于沟通程序错误的能力－不是体现在错误本身的内在严重程度－而是体现在确定这个错误是否需要修复。

       如果这是一个可怕的想法，你可能会想，“等等！我讨厌写作，我并不擅长写作。怎么样才能够通过编写bug report来决定错误的命运呢？”它要吸引大家相信错误是为他们说话的－任何一个头脑正常的人都应该主动地查看一个特定的错误是足够可怕的以致要被修复。不幸的是，事实并不是这样。

       但是好消息是：有效的和软件开发人员、项目组沟通的能力不是由你在高校英语课程中的表现所决定的。

       这不是关于用有趣的词语编写流畅散文，也不是关于优秀语法和拼写的方法。它是有关仅用能够表达你观点的词语明白地表述错误的方法。太多地话将会使你的观点陷入茫然无措中。太少地话又会使他人用自己的假设去填补隔阂－通常是对软件有害的部分。如果你不是很确信是什么样的错误，那么不管你的bug report写得怎么好，也没有人知道那是什么样的错误。

       这篇文章主要讨论你现在能够开始着手提高人们倾听你发现的错误的机会的4个方法。

1. 了解你的听众

       毋庸置疑，任何写作课都会告诉你必须了解你是为谁编写bug report。

       每份bug report至少有两个听众：必须要修复错误的人和决定错误命运的人或团体。有时一个人会同时负责这两份工作，但是仍然是两个不同的听众，只是一起发生在同一个人身上罢了。

       你的第一个听众－那个必须修复错误的人需要清楚，明确的步骤以重现错误。信息越多越好。针对这个目的，我们称这个人为“开发人员”。开发人员需要关于我们操作了什么和我们看见了什么的准确信息。

       你的第二个听众－决定错误命运的人或团体需要知道如果不修复此错误的后果。这个听众需要精练的语句以抓住他们的注意力并且引发对错误的相关连问题的讨论。基于这个目的，我们称他为“错误审核委员会”。在使错误得以修复的过程中你的角色是帮助错误审核委员会了解不修复错误的风险远远超过修复错误可能发生的风险。

       你越了解你的开发人员和错误审核委员会如何工作，你就越可以根据他们的需要裁减你的bug report。尽力在私底下设法了解你的听众。如果你能够出席错误审核委员会会议，尝试这样做。你将学习到许多关于你的听众是如何思考的知识。

2. 选择一个好的标题

      一般把用于描述错误的短句称为错误的标题或描述。这是bug report中最重要的部分。错误审核委员会成员经常通过它来决定错误是否可以推迟修复。如果标题没有力度，委员会成员可能认为它是不值得花费太多的时间。（毕竟，在接下来的2个小时里还有145个以上的错误要审核。）

       以下是一些示例：

好的 ：超时后在退出时崩溃了

太长的 ：在数据库不可用后你又保存记录的更改 , 然后从文件菜单中选择退出时程序崩溃了

不足够的信息 ：程序崩溃了

太模糊 ：当数据库离线时出现问题

标题变成了一种给项目组提供检查和调查错误的方法。和数据相比，人们更容易记词语。人们更愿意记得“在windows2000下不能够安装”的错误，而不是类似“＃23423”错误，而且在以后人们还会利用这些关键词搜索错误。

      编写一个好的，简明的错误标题是不容易的。和编写bug report的其他部分相比，应该多花些时间构造理想的错误标题。要确信标题是足够短以便能够在显示错误的屏幕上和由缺陷跟踪系统生成的报表中显示完全（不会折行）。标题不必是完美的语法，而应简短并一针见血。

3. 书写清楚，明确的步骤

       你提交给开发人员的步骤应该提供如何产生错误的信息，这样错误就能够被发现并且修复。它也需要给错误审核委员会提供错误发生的环境。

唯一正确 ：

1．  运行客户端

2．  找出一个记录

3．  更改记录但不存盘

4．  使数据库服务器脱机

5．  尝试保存记录

6．  收到一个超时的错误

7．  退出客户端

结果：崩溃

马虎的（有很大空间让人产生误解的 ）：

使数据库服务器脱机，保存，然后退出，崩溃了。

太多冗余的信息（不能够指出什么是引发错误的最关键原因）

1．  运行客户端

2．  为输入新的条目查询数据库

3．  打开一个浏览器

4．  在 yahoo.com 上浏览新闻

5．  关闭浏览器

6．  选择一个条目

7．  把种类从“蔬菜” 更改到“水果”

8．  使数据库服务器脱机

9．  尝试保存记录

10．                       收到一个超时的错误

11．                       退出客户端

结果：崩溃

在这个例子中，测试人员记录在发现错误之前他所作的一切，但是他没有检查是不是每个步骤都是必要的，例如从yahoo.com阅读新闻。

如果你只写下那些产生错误必不可少的步骤，开发人员将很少告诉你他们不能够重现错误，同样错误什么委员会也会很少决定“没有人将会做到那个程度！”

但是如果每个步骤都是必须的，怎么办呢？如果错误只在你执行了一些看上去没有关系的步骤后出现了，那么在bug report中记录下这些步骤。你可以在那些看上去没有逻辑关系的步骤后写上“必须的步骤”，或者你可以在bug report的开始部分加上注释：“注意－这里的每一个步骤都是重现错误的必要步骤。

编写清晰的步骤同样可以在验证修复过程中提供帮助，特别是在另一个测试人员做验证的时候。

4. 解释错误的影响，不只是症状

一些bug report是令人误解的。从错误的表层看是无伤大雅的，但是如果在你检查错误的牵连时，你发现它是一个非常严重的问题。如果你在错误审核委员会，你会拥护先修改哪一个错误呢？

1．  关于“一个令人讨厌的对话框阻止关闭应用程序”的报告

2．  关于“在退出时应用程序中止了” 的报告

这两个是同一个错误。差异完全在于测试人员如何编写bug report。

在此提到的“令人讨厌的对话框”是指Windows操作系统中显示不能退出进程的窗口（“这个Windows应用程序不能响应结束任务的请求。。。”）。测试人员在试图关闭机器而不是退出应用程序时发现这个问题。应用程序没有等待来自用户的输入，因此退出失败是没有原因的。实际上，这个症状指出了更深的问题－在第一个关于“令人讨厌的对话框”的bug report被推迟修复时几乎要遗漏的问题。

这个 “令人讨厌的对话框”的bug report存在着两个问题。首先，它不精确。如果测试人员在步骤中包括了“令人讨厌的对话框”中的文字，决策者可以认识到对话框是一个严重的问题而不是一个微小的干扰。第二，这份报告没有指出错误的其他隐藏的问题：应用程序被中止了。

结论

我们都想把自己的工作变得与众不同。我们想知道是因为我们努力的工作而使得软件的最终版本更好。我们用来沟通错误的能力在我们是否有尽我们希望多地影响软件的最终版本中是决定因素。

因此当你编写bug report时，记住你的听众，选择一个好的标题，清楚的记录步骤并解释错误的影响。你的bug report将会因为你花在它上面的格外努力而更好，并且有更多的错误被修复。最终将达到我们期望的结果－使错误在伤害用户之前得到修复。