如何有效地报告 Bug

如何有效地报告 Bug

做者：Simon Tatham 专业的自由软件程序员

翻译：Dasn

[ English | Português | 简体中文 | Česky | Dansk | Deutsch | Español | Français | Magyar | Italiano | 日本語 | Nederlands | Polski | Русский | 繁體中文 ]

引言

为公众写过软件的人，大概都收到过很拙劣的bug（计算机程序代码中的错误或程序运行时的瑕疵——译者注）报告，例如：

在报告中说“很差用”；

所报告内容毫无心义；

在报告中用户没有提供足够的信息；

在报告中提供了错误信息；

所报告的问题是因为用户的过失而产生的；

所报告的问题是因为其余程序的错误而产生的；

所报告的问题是因为网络错误而产生的；

这即是为何“技术支持”被认为是一件可怕的工做，由于有拙劣的bug报告须要处理。然而并非全部的bug报告都使人生厌：我在业余时间维护自由软件，有时我会收到很是清晰、有帮助而且“有内容”的bug报告。

在这里我会尽力阐明如何写一个好的bug报告。我很是但愿每个人在报告bug以前都读一下这篇短文，固然我也但愿用户在给我报告bug以前已经读过这篇文章。

简单地说，报告bug的目的是为了让程序员看到程序的错误。您能够亲自示范，也能够给出能致使程序出错的、详尽的操做步骤。若是程序出错了，程序员会收集额外的信息直到找到错误的缘由；若是程序没有出错，那么他们会请您继续关注这个问题，收集相关的信息。

在bug报告里，要设法搞清什么是事实（例如：“我在电脑旁”和“XX出现了”）什么是推测（例如：“我想问题多是出在……”）。若是愿意的话，您能够省去推测，可是千万别省略事实。

当您报告bug的时候（既然您已经这么作了），必定是但愿bug获得及时修正。因此此时针对程序员的任何过激或亵渎的言语（甚至谩骂）都是与事无补 的——由于这多是程序员的错误，也有多是您的错误，也许您有权对他们发火，可是若是您能多提供一些有用的信息（而不是激愤之词）或许bug会被更快的 修正。除此之外，请记住：若是是免费软件，做者提供给咱们已是出于好心，因此要是太多的人对他们无礼，他们可能就要“收起”这份好心了。

“程序很差用”

程序员不是弱智：若是程序一点都很差用，他们不可能不知道。他们不知道必定是由于程序在他们看来工做得很正常。因此，或者是您做过一些与他们不一样的操做，或者是您的环境与他们不一样。他们须要信息，报告bug也是为了提供信息。信息老是越多越好。

许多程序，特别是自由软件，会公布一个“已知bug列表”。若是您找到的bug在列表里已经有了，那就没必要再报告了，可是若是您认为本身掌握的信息比列表中的丰富，那不管如何也要与程序员联系。您提供的信息可能会使他们更简单地修复bug。

本文中提到的都是一些指导方针，没有哪一条是必须恪守的准则。不一样的程序员会喜欢不一样形式的bug报告。若是程序附带了一套报告bug的准则，必定要读。若是它与本文中提到的规则相抵触，那么请以它为准。

若是您不是报告bug，而是寻求帮助，您应该说明您曾经到×××过答案，（例如：我看了第四章和第五章的第二节，但我找不到解决的办法。）这会使程序员了解用户喜欢到哪里去找答案，从而使程序员把帮助文档作得更容易使用。

“演示给我看”

报告bug的最好的方法之一是“演示”给程序员看。让程序员站在电脑前，运行他们的程序，指出程序的错误。让他们看着您启动电脑、运行程序、如何进行操做以及程序对您的输入有何反应。

他们对本身写的软件了如指掌，他们知道哪些地方不会出问题，而哪些地方最可能出问题。他们本能地知道应该注意什么。在程序真的出错以前，他们可能已经注意到某些地方不对劲，这些都会给他们一些线索。他们会观察程序测试中的每个细节，而且选出他们认为有用的信息。

这些可能还不够。也许他们以为还须要更多的信息，会请您重复刚才的操做。他们可能在这期间须要与您交流一下，以便在他们须要的时候让bug从新出 现。他们可能会改变一些操做，看看这个错误的产生是个别问题仍是相关的一类问题。若是您不走运，他们可能须要坐下来，拿出一堆开发工具，花上几个小时来好好地研究一下。可是最重要的是在程序出错的时候让程序员在电脑旁。一旦他们看到了问题，他们一般会找到缘由并开始试着修改。

“告诉我该怎么作”

现在是网络时代，是信息交流的时代。我能够点一下鼠标把本身的程序送到俄罗斯的某个朋友那里，固然他也能够用一样简单的方法给我一些建议。可是若是个人程序出了什么问题，我不可能在他旁边。“演示”是很好的办法，可是经常作不到。

若是您必须报告bug，而此时程序员又不在您身边，那么您就要想办法让bug重现在他们面前。当他们亲眼看到错误时，就可以进行处理了。

确切地告诉程序员您作了些什么。若是是一个图形界面程序，告诉他们您按了哪一个按钮，依照什么顺序按的。若是是一个命令行程序，精确的告诉他们您键入了什么命令。您应该尽量详细地提供您所键入的命令和程序的反应。

把您能想到的全部的输入方式都告诉程序员，若是程序要读取一个文件，您可能须要发一个文件的拷贝给他们。若是程序须要经过网络与另外一台电脑通信，您或许不能把那台电脑复制过去，但至少能够说一下电脑的类型和安装了哪些软件（若是能够的话）。

“哪儿出错了？在我看来一切正常哦！”

若是您给了程序员一长串输入和指令，他们执行之后没有出现错误，那是由于您没有给他们足够的信息，可能错误不是在每台计算机上都出现，您的系统可能 和他们的在某些地方不同。有时候程序的行为可能和您预想的不同，这也许是误会，可是您会认为程序出错了，程序员却认为这是对的。

一样也要描述发生了什么。精确的描述您看到了什么。告诉他们为何您以为本身所看到的是错误的，最好再告诉他们，您认为本身应该看到什么。若是您只是说：“程序出错了”，那您极可能漏掉了很是重要的信息。

若是您看到了错误消息，必定要仔细、准确的告诉程序员，这确实很重要。在这种状况下，程序员只要修正错误，而不用去找错误。他们须要知道是什么出问题了，系统所报的错误消息正好帮助了他们。若是您没有更好的方法记住这些消息，就把它们写下来。只报告“程序出了一个错”是毫无心义的，除非您把错误消息一块报上来。

特殊状况下，若是有错误消息号，必定要把这些号码告诉程序员。不要觉得您看不出任何意义，它就没有意义。错误消息号包含了能被程序员读懂的各类信息，而且颇有可能包含重要的线索。给错误消息编号是由于用语言描述计算机错误经常使人费解。用这种方式告诉您错误的所在是一个最好的办法。

在这种情形下，程序员的排错工做会十分高效。他们不知道发生了什么，也不可能到现场去观察，因此他们一直在搜寻有价值的线索。错误消息、错误消息号以及一些莫名其妙的延迟，都是很重要的线索，就像办案时的指纹同样重要，保存好。

若是您使用UNIX系统，程序可能会产生一个内核输出（coredump）。内核输出是特别有用的线索来源，别扔了它们。另外一方面，大多数程序员不 喜欢收到含有大量内核输出文件的EMAIL，因此在发邮件以前最好先问一下。还有一点要注意：内核输出文件记录了完整的程序状态，也就是说任何秘密（可能 当时程序正在处理一些私人信息或秘密数据）均可能包含在内核输出文件里。

“出了问题以后，我作了……”

当一个错误或bug发生的时候，您可能会作许多事情。可是大多数人会使事情变的更糟。个人一个朋友在学校里误删了她全部的Word文件，在找人帮忙 以前她重装了Word，又运行了一遍碎片整理程序，这些操做对于恢复文件是毫无益处的，由于这些操做搞乱了磁盘的文件区块。恐怕在这个世界上没有一种反删 除软件能恢复她的文件了。若是她不作任何操做，或许还有一线但愿。

这种用户仿佛一只被逼到墙角的鼬（黄鼠狼、紫貂一类的动物——译者注）：背靠墙壁，面对死亡的降临奋起反扑，疯狂***。他们认为作点什么总比什么都不作强。然而这些在处理计算机软件问题时并不适用。

不要作鼬，作一只羚羊。当一只羚羊面对料想不到的状况或受到惊吓时，它会一动不动，是为了避免吸引任何注意，与此同时也在思考解决问题的最好办法（若是羚羊有一条技术支持热线，此时占线。）。而后，一旦它找到了最安全的行动方案，它便去作。

当程序出毛病的时候，马上中止正在作的任何操做。不要按任何健。仔细地看一下屏幕，注意那些不正常的地方，记住它或者写下来。然 后慎重地点击“肯定” 或“取消”，选择一个最安全的。学着养成一种条件反射——一旦电脑出了问题，先不要动。要想摆脱这个问题，关掉受影响的程序或者从新启动计算机都很差，一 个解决问题的好办法是让问题再次产生。程序员们喜欢能够被重现的问题，快乐的程序员能够更快并且更有效率的修复bug。

“我想粒子的跃迁与错误的极化有关”

并不仅是非专业的用户才会写出拙劣的bug报告，我见过一些很是差的bug报告出自程序员之手，有些仍是很是优秀的程序员。

有一次我与另外一个程序员一块儿工做，他一直在找代码中的bug，他经常遇到一个bug，可是不会解决，因而就叫我帮忙。“出什么毛病了？”我问。而他 的回答却老是一些关于bug的意见。若是他的观点正确，那的确是一件好事。这意味着他已经完成了工做的一半，而且咱们能够一块儿完成另外一半工做。这是有效率 并有用的。

但事实上他经常是错的。这就会使咱们花上半个小时在本来正确的代码里来回寻找错误，而实际上问题出在别的地方。我敢确定他不会对医生这么作。“大 夫，我得了Hydroyoyodyne（真是怪病——译者），给我开个方子”，人们知道不应对一位医生说这些。您描述一下症状，哪一个地方不舒服，哪里疼、 起皮疹、发烧……让医生诊断您得了什么病，应该怎样治疗。不然医生会把您当作疑心病或精神病患者打发了，这彷佛没什么不对。

作程序员也是同样。即使您本身的“诊断”有时真的有帮助，也要只说“症状”。“诊断”是可说可不说的，可是“症状”必定要说。一样，在bug报告里面附上一份针对bug而作出修改的源代码是有用处的，但它并不能替代bug报告自己。

若是程序员向您询问额外的信息，千万别应付。曾经有一我的向我报告bug，我让他试一个命令，我知道这个命令很差用，但我是要看看程序会返回一个什 么错误（这是很重要的线索）。可是这位老兄根本就没试，他在回复中说“那确定很差用”，因而我又花了好些时间才说服他试了一下那个命令。

用户多动动脑筋对程序员的工做是有帮助的。即便您的推断是错误的，程序员也应该感谢您，至少您想去帮助他们，使他们的工做变的更简单。不过千万别忘了报告“症状”，不然只会使事情变得更糟。

“真是奇怪，刚才还很差用，怎么如今又好了？”

“间歇性错误”着实让程序员发愁。相比之下，进行一系列简单的操做便能致使错误发生的问题是简单的。程序员能够在一个便于观察的条件下重复那些操 做，观察每个细节。太多的问题在这种状况下不能解决，例如：程序每星期出一次错，或者偶然出一次错，或者在程序员面前从不出错（程序员一离开就出错。 ——译者）。固然还有就是程序的截止日期到了，那确定要出错。

大多数“间歇性错误”并非真正的“间歇”。其中的大多数错误与某些地方是有联系的。有一些错误多是内存泄漏产生的，有一些多是别的程序在不恰当的时候修改某个重要文件形成的，还有一些可能发生在每个小时的前半个小时中（我确实遇到过这种事情）。

一样，若是您能使bug重现，而程序员不能，那颇有多是他们的计算机和您的计算机在某些地方是不一样的，这种不一样引发了问题。我曾写过一个程序，它的窗口能够蜷缩成一个小球呆在屏幕的左上角，它在别的计算机上只能在 800x600 的解析度工做，可是在个人机器上却能够在 1024x768 下工做。

程序员想要了解任何与您发现的问题相关的事情。有可能的话您到另外一台机器上试试，多试几回，两次，三次，看看问题是否是常常发生。若是问题出如今您 进行了一系列操做以后，不是您想让它出现它就会出现，这就有多是长时间的运行或处理大文件所致使的错误。程序崩溃的时候，您要尽量的记住您都作了些什 么，而且若是您看到任何图形,也别忘了提一下。您提供的任何事情都是有帮助的。即便只是归纳性的描述（例如：当后台有EMACS运行时，程序经常出错）， 这虽然不能提供致使问题的直接线索，可是可能帮助程序员重现问题。

最重要的是：程序员想要肯定他们正在处理的是一个真正的“间歇性错误”呢，仍是一个在另外一类特定的计算机上才出现的错误。他们想知道有关您计算机的 许多细节，以便了解您的机器与他们的有什么不一样。有许多细节都依仗特定的程序，可是有一件东西您必定要提供——版本号。程序的版本、操做系统的版本以及与 问题有关的程序的版本。

“我把磁盘装进了 Windows……”

表意清楚在一份bug报告里是最基本的要求。若是程序员不知道您说的是什么意思，那您就跟没说同样。我收到的bug报告来自世界各地，有许可能是来自 非英语国家，他们一般为本身的英文很差而表示歉意。总的来讲，这些用户发来的bug报告一般是清晰并且有用的。几乎全部不清晰的bug报告都是来自母语是 英语的人，他们老是觉得只要本身随便说说，程序员就能明白。

• 精确。若是作相同的事情有两种方法，请说明您用的是哪种。例如：“我选择了‘载入’”，可能意味着“我用鼠标点击‘载入’”或“我按下了‘ALT+L’”，说清楚您用了哪一种方法，有时候这也有关系。
• 详细。信息宁多毋少！若是您说了不少，程序员能够略去一部分，但是若是您说的太少，他们就不得不回过头再去问您一些问题。有一次我收到了一份bug报告只有一句话，每一次我问他更多事情时，他每次的回复都是一句话，因而我花了几个星期的时间才获得了有用的信息。
• 慎用代词。诸如“它”，“窗体”这些词，当它们指代不清晰的时候不要用。来看看这句话：“我运行了FooApp，它弹出一个警 告窗口，我试着关掉它，它就崩溃了。”这种表述并不清晰，用户究竟关掉了哪一个窗口？是警告窗口仍是整个FooApp程序？您能够这样说，“我运行 FooApp程序时弹出一个警告窗口，我试着关闭警告窗口，FooApp崩溃了。”这样虽然罗嗦点，可是很清晰不容易产生误解。
• 检查。从新读一遍您写的bug报告，您以为它是否清晰？若是您列出了一系列能致使程序出错的操做，那么照着作一遍，看看您是否是漏写了一步。

小结：

• bug报告的首要目的是让程序员亲眼看到错误。若是您不能亲自作给他们看，给他们能使程序出错的详细的操做步骤。
• 若是首要目的不能达成，程序员不能看到程序出错。这就须要bug报告的第二个目的来描述程序的什么地方出毛病了。详细的描述每一件事情：您看到了什么，您想看到什么，把错误消息记下来，尤为是“错误消息号”。
• 当您的计算机作了什么您料想不到的事，不要动！在您平静下来以前什么都别作。不要作您认为不安全的事。
• 尽可能试着本身“诊断”程序出错的缘由（若是您认为本身能够的话）。即便作出了“诊断”，您仍然应该报告“症状”。
• 若是程序员须要，请准备好额外的信息。若是他们不须要，就不会问您要。他们不会故意为难本身。您手头上必定要有程序的版本号，它极可能是必需品。
• 表述清楚，确保您的意思不能被曲解。
• 总的来讲，最重要的是要作到精确。程序员喜欢精确。

---

声明：我从没有真的看见过鼬和羚羊，个人比喻可能不恰当。

版权全部 Simon Tatham 1999

本文属于OPL（OpenContent License），请在复制和使用本文时自觉遵照OPL。

对本文的任何意见和批评请发送至：

英文版：anakin@pobox.com

中文版：dasn@users.sf.net

 

http://www.chiark.greenend.org.uk/~sgtatham/bugs-cn.html