作者：Simon Tatham 专业的自由软件程序员
翻译：Dasn
原文链接/不同语言版本
十分有用的一篇文章，为了提醒自己做一个好的bug报告者，特保存文章在此。另外，为了以后方便查阅，提取了文章内容，加入自己的一些想法。

引言

拙劣的bug（计算机程序代码中的错误或程序运行时的瑕疵——译者注）报告例子：

• 在报告中说“不好用”
• 所报告内容毫无意义
• 在报告中用户没有提供足够的信息
• 在报告中提供了错误信息
• 所报告的问题是由于用户的过失而产生的
• 所报告的问题是由于其他程序的错误而产生的
• 所报告的问题是由于网络错误而产生的

“技术支持”很可怕的工作？——因为有拙劣的bug报告需要处理。

好的bug报告的特性：非常清晰、有帮助并且“有内容”。

• 本书所有指导方针，非必须恪守
  不同的程序员会喜欢不同形式的bug报告。

• 以程序附带了一套报告bug的准则为准

如何写一个好的bug报告

基本要求

• 表意清楚
  如果程序员不知道您说的是什么意思，那您就跟没说一样。尽量做到清晰并且有用

• 精确
  如果做相同的事情有两种方法，请说明您用的是哪一种。例如：“我选择了‘载入’”，可能意味着“我用鼠标点击‘载入’”或“我按下了‘ALT+L’”，说清楚您用了哪种方法，有时候这也有关系。

• 详细
  信息宁多毋少！如果您说了很多，程序员可以略去一部分，可是如果您说的太少，他们就不得不回过头再去问您一些问题。

• 慎用代词
  诸如“它”，“窗体”这些词，当它们指代不清晰的时候不要用。来看看这句话：“我运行了FooApp，它弹出一个警告窗口，我试着关掉它，它就崩溃了。”这种表述并不清晰，用户究竟关掉了哪个窗口？是警告窗口还是整个FooApp程序？您可以这样说，“我运行FooApp程序时弹出一个警告窗口，我试着关闭警告窗口，FooApp崩溃了。”这样虽然罗嗦点，但是很清晰不容易产生误解。

• 检查
  重新读一遍您写的bug报告，您觉得它是否清晰？如果您列出了一系列能导致程序出错的操作，那么照着做一遍，看看您是不是漏写了一步。

注意：

• 报告bug的目的是为了让程序员看到程序的错误
  您可以亲自示范，也可以给出能导致程序出错的、详尽的操作步骤。如果程序出错了，程序员会收集额外的信息直到找到错误的原因；如果程序没有出错，那么他们会请您继续关注这个问题，收集相关的信息。

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

• 少一点激愤之词，多一点有用的信息
  当您报告bug的时候（既然您已经这么做了），一定是希望bug得到及时修正。所以此时针对程序员的任何过激或亵渎的言语（甚至谩骂）都是与事无补的——因为这可能是程序员的错误，也有可能是您的错误，也许您有权对他们发火，但是如果您能多提供一些有用的信息（而不是激愤之词）或许bug会被更快的修正。

• 常怀感恩之心
  请记住：如果是免费软件，作者提供给我们已经是出于好心，所以要是太多的人对他们无礼，他们可能就要“收起”这份好心了。

“出了问题之后，该怎么做”

• 一旦电脑出了问题，先不要动

• 不要按任何健。仔细地看一下屏幕，注意那些不正常的地方，记住它、写下来、或者拍下来。

• 慎重地点击“确定” 或“取消”，选择一个最安全的。

出现问题之后，关掉受影响的程序或者重新启动计算机都不好，一个解决问题的好办法是让问题再次产生。程序员们喜欢可以被重现的问题，快乐的程序员可以更快而且更有效率的修复bug

如果程序不好用

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

• 报告bug：提供尽可能多的信息，以供程序员重现——操作、环境
  程序员不是弱智：如果程序一点都不好用，他们不可能不知道。他们不知道一定是因为程序在他们看来工作得很正常。所以，或者是您作过一些与他们不同的操作，或者是您的环境与他们不同。他们需要信息，报告bug也是为了提供信息。信息总是越多越好。

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

报告bug的最好的方法之一——“演示重现”

报告bug的最好的方法之一是“演示”给程序员看。让程序员站在电脑前，运行他们的程序，指出程序的错误。让他们看着您启动电脑、运行程序、如何进行操作以及程序对您的输入有何反应。他们会观察程序测试中的每一个细节，并且选出他们认为有用的信息。

也许他们觉得还需要更多的信息，会请您重复刚才的操作。他们可能在这期间需要与您交流一下，以便在他们需要的时候让bug重新出现。他们可能会改变一些操作，看看这个错误的产生是个别问题还是相关的一类问题。如果您不走运，他们可能需要坐下来，拿出一堆开发工具，花上几个小时来好好地研究一下。

无法直接演示的时候

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

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

• 把您能想到的所有的输入方式都告诉程序员
  如果程序要读取一个文件，您可能需要发一个文件的拷贝给他们。如果程序需要通过网络与另一台电脑通讯，您或许不能把那台电脑复制过去，但至少可以说一下电脑的类型和安装了哪些软件（如果可以的话）。

无法重现

• 不是bug——彼此认知上的差异
  如果您给了程序员一长串输入和指令，他们执行以后没有出现错误，那是因为您没有给他们足够的信息，可能错误不是在每台计算机上都出现，您的系统可能和他们的在某些地方不一样。有时候程序的行为可能和您预想的不一样，这也许是误会，但是您会认为程序出错了，程序员却认为这是对的。

• 详细描述Bug信息——而不是“程序出错了”
  精确的描述发生了什么。精确的描述您看到了什么。告诉他们为什么您觉得自己所看到的是错误的，最好再告诉他们，您认为自己应该看到什么。

• 如果您看到了错误消息/错误消息号，一定要仔细、准确的告诉程序员
  只报告“程序出了一个错”是毫无意义的，除非您把错误消息一块报上来。
  不要以为您看不出错误消息/错误消息号代表什么意义，它就没有意义。
  有价值的线索——错误消息、错误消息号、coredump以及一些莫名其妙的延迟，就像办案时的指纹一样重要，保存好。这样的话，程序员的排错工作会十分高效。
  错误消息系统所报的错误消息正好帮助了他们知道是什么出问题。在这种情况下，程序员只要修正错误，而不用去找错误。
  错误消息号包含了能被程序员读懂的各种信息，并且很有可能包含重要的线索。给错误消息编号是因为用语言描述计算机错误常常令人费解。用这种方式告诉您错误的所在是一个最好的办法。如果您没有更好的方法记住这些消息，就把它们写下来。
  内核输出文件记录了完整的程序状态，也就是说任何秘密（可能当时程序正在处理一些私人信息或秘密数据）都可能包含在内核输出文件里。

• 间歇性问题？
  例如：程序每星期出一次错，或者偶然出一次错，或者在程序员面前从不出错（程序员一离开就出错。——译者）。当然还有就是程序的截止日期到了，那肯定要出错。
  大多数“间歇性错误”并不是真正的“间歇”。其中的大多数错误与某些地方是有联系的。有一些错误可能是内存泄漏产生的，有一些可能是别的程序在不恰当的时候修改某个重要文件造成的，还有一些可能发生在每一个小时的前半个小时中（我确实遇到过这种事情）。
  程序员想要确定他们正在处理的是一个真正的“间歇性错误”呢，还是一个在另一类特定的计算机上才出现的错误。他们想知道有关您计算机的许多细节，以便了解您的机器与他们的有什么不同。有许多细节都依仗特定的程序，但是有一件东西您一定要提供——版本号。程序的版本、操作系统的版本以及与问题有关的程序的版本。

如果程序员向您询问额外的信息，或者希望你能进行一些操作，记住要好好合作，这样可以快速缩小问题范围。
即便您自己的“诊断”有时真的有帮助，也要只说“症状”。“诊断”是可说可不说的，但是“症状”一定要说。就像去医院，不可能不说症状，直接让医生给你治疗自诊断出来的结果。

小结：

bug报告的基础要求是表述清楚，确保您的意思不能被曲解。

bug报告的首要目的是让程序员亲眼看到错误。如果您不能亲自做给他们看，给他们能使程序出错的详细的操作步骤。

如果首要目的不能达成，程序员不能看到程序出错。这就需要bug报告的第二个目的来描述程序的什么地方出毛病了。详细的描述每一件事情：您看到了什么，您想看到什么，把错误消息记下来，尤其是“错误消息号”。

当您的计算机做了什么您料想不到的事，不要动！在您平静下来之前什么都别做。不要做您认为不安全的事。

尽量试着自己“诊断”程序出错的原因（如果您认为自己可以的话）。即使做出了“诊断”，您仍然应该报告“症状”。

如果程序员需要，请准备好额外的信息。如果他们不需要，就不会问您要。他们不会故意为难自己。您手头上一定要有程序的版本号，它很可能是必需品。

总的来说，最重要的是要做到精确。程序员喜欢精确。

---

版权所有 Simon Tatham 1999
本文属于OPL（OpenContent License），请在复制和使用本文时自觉遵守OPL。
对本文的任何意见和批评请发送至：
英文版：anakin@pobox.com
中文版：dasn@users.sf.net