[转载]如何有效地报告错误

遇到任何问题时, 看看这篇文章, 照上面说的做给自己看看, 很多问题可能就这样子解决掉囉~

作者: Simon Tatham, 专业及免费软件程式师
翻译:梅普华

介绍

写过供大众使用软件的人可能都收过一份以上的烂错误报告. 有啥都没讲的报告(这个程式不会动), 有不合理的报告或资讯不足的报告, 也有提供不正确资讯的报告. 还有一些报告查到后来不是使用者自己搅错, 就是其他程式惹祸, 或是网络断线等等.

有个理由可以解释为什么技术支援工作这么难做, 原因就是这些乱七八糟的错误报告. 不过并非所有错误报告都是这么糟糕. 我工作之余有在维护免费软件, 有时候会收到一些非常清楚有帮助而且很有内容的错误报告.

我会试着在这篇短文中清楚说明良好错误报告的重点. 基本上我希望全世界的人在报告任何错误前都能读读这篇短文. 当然我更希望每个送错误报告给我的人都读过.

简而言之, 错误报告的目的是要让程式师能亲眼目睹程式出错. 你可以亲身示范给他们看, 也可以提供一份详细而彻底的指令教他们如何重现问题, 如果他们可以重现问题, 就会试着收集更多资讯去了解问题的原因. 如果他们无法重现问题, 就只能要你帮他们收集资讯.

在错误报告中, 必须要把真实发生的事实(我在电脑前看到这个状况)和臆测(我认为问题可能是)很明显的区分开来. 必要时可以把臆测略过不提, 不过事实绝对不能漏.

因为你希望错误能被修正, 才会提出报告错误. 没有必要对程式师恶言相向或故作无助: 问题有可能是他们搞的, 但也可能是你自己惹的. 或许对程式师发脾气有点道理, 不过如果你能协助提供所有必要的资讯, 问题就能尽快修好. 另外也请记住, 既然程式是免费的, 表示作者是基于好心而提供的. 如果很多人对他们不礼貌, 他们可能就不会那么好心了.

"程式不会动."

多少相信程式师的基本智能吧. 如果程式完全不会动, 他们应该会发现的. 既然他们没有发现, 表示他们用的时候没问题. 所以要不是你的作法和他们不同, 就是你的环境和他们不同. 他们需要资讯, 错误报告的目的就是提供这些资讯. 资讯过多往往好过资讯不足.

很多程式(特别是免费的)都会公开已知的问题清单. 如果你能找到这样的已知问题清单, 应该好好读一遍, 看看你刚发现的问题是否为新问题. 如果是已知的问题就不值得再报告一次, 不过如果你认为你的资讯比较齐全, 还是可以联络程式师. 因为如果你能提供一些原本没有的资讯, 他们或许能更轻易地解决问题.

这篇短文充满了指引原则. 这些原则都不是绝对不变的规定. 每个程式师自有期望的错误报告方式. 如果程式附有自己的错误报告指引原则, 应该要读一遍. 如果程式所附的指引原则与本文冲突, 就照程式的规矩来做.

如果你不是在报告错误, 而是就程式使用上的问题求助, 应该说明已经在那些地方找过答案(我看了第4章的5.2节, 可是找不到任何相关的内容). 这会让程式师知道人们会期望到什么地方找答案, 以后就能让文件更易使用.

"试给我看."

报告错误的最佳方法之一就是直接示范给程式师看. 让他们站到你的电脑前面, 执行他们的软件, 然后指出问题所在. 让他们看着你打开电脑, 看着你执行并操作软件, 并且看到软件所产生的反应.

程式师对自己的程式了若指掌. 他们知道哪些部份绝对正确, 也知道哪些部份可能会有问题. 他们光凭直觉就知道要找些什么. 在程式跑出明显的错误之前, 他们可能已经提早注意到一些细微的错误并从中得到线索. 他们可以观察电脑所有的执行过程, 并且挑出对他们重要的资讯.

有了这些可能还不够. 他们可能会觉得还需要更多资讯, 并且要求你重复执行给他们看. 他们也可能会要你说明整个操作过程, 以便他们能自己重复重现问题. 他们也可能会改变操作过程多试几次, 看看问题只在某一种状况发生, 还是在相关的多种状况下都有出现. 如果运气不好, 他们可能得坐下来花上几个小时拿出整组开发工具真正深入调查. 不过最重要的还是让程式师看到电脑出错. 只要他们能看到问题发生, 通常都可以由此开始尝试修正问题.

"教我如何做给自己看."

现在是个Internet时代. 同时也是全球通讯的时代. 在这个时代只要按个钮就能把我的软件传送给位在俄罗斯的某人, 对方也一样能轻易地把意见传给我. 不过如果他用我的程式遇到问题, 可就没法子把我找到他电脑前看着程式出错. 如果能的话, "试给我看"的作法是很好的, 不过通常都做不到.

如果你必须向一个不可能到你身旁的程式师报告错误, 首要目标是让他们能重现问题. 希望让程式师执行自己的那份程式, 进行相同的操作, 然后以相同的方式出错. 当他们能亲眼看到问题发生, 就可以开始处理.

所以你得丝毫不差地把自己做的事告诉他们. 如果这是个有图形接口的程式, 告诉他们你按了哪些按钮以及按各按钮的次序. 如果是输入命令执行的程式, 就要精确地告知你所输入的命令. 可能的话应该尽量提供整个过程的精确记录, 里面包含所有你所输入的命令以及电脑的反应.

把你所能想到的所有输入都给程式师. 如果程式由某个档案读资料, 你可能也得送一份档案拷贝过去. 如果程式会透过网络和另一台电脑通讯, 你可能没法子把另一台电脑送过去, 不过至少可以说明电脑的类型以及上面所执行的软件(如果能的话).

"我这里能正常执行. 究竟出了什么问题?"

如果你提供程式师一长串输入和动作, 他们照着执行自己的程式, 结果却一切正常, 表示你提供给他们的资讯还不够. 可能是这个问题并不会在每台电脑出现; 或是你和他们的系统间有某些差异. 也可能是你误解了这个程式的作用. 你们看到一模一样的显示输出, 可是你认为这样的输出是错的, 而他们知道这是对的.

所以你也得叙述发生的事情. 精确地告知你看到的内容. 告知为何你认为所看到的内容是错的; 如果能告知你预期看到的结果更好. 如果你用"然后就出问题了"这种写法, 就会略过了一些非常重要的资讯.

如果你看到错误讯息, 应该要小心精确地告诉程式师讯息的内容. 这些讯息非常重要! 在目前这个阶段, 程式师只是想找出问题所在, 并不会尝试去修正问题. 他们必须知道什么地方出错, 而那些错误讯息正是电脑对问题的最佳叙述. 如果没有其他方法能轻易记下问题就把问题抄下来. 不过如果不能同时报告错误讯息的内容, 光说程式出错是没有意义的.

如果错误讯息里有数字时更要特别注意, 一定要让程式师知道那些数字. 你看不懂并不表示没有意义. 这些数字里面隐藏有程式师能解读的各种资讯, 而且很可能包含极重要的线索. 错误讯息里会有数字, 是因为电脑无法精确地用文字回报错误, 只能尽量用其他方式把重要的讯息呈现出来.

在这个阶段程式师事实上是在做侦探一样的工作. 他们不知道发生什么事, 也无法接近现场亲眼目睹, 所以只能努力找寻线索把问题挖出来. 错误讯息, 无法理解的数字代码, 甚至无法解释的迟滞都和犯罪现场的指纹一样重要. 所以一定要保存起来.

如果你用的是Unix, 程式可能会产生一个核心倾印(core dump). 核心倾印是个很好的线索来源, 所以绝对不要删掉. 不过大部份的程式师都不喜欢突然收到附有核心倾印大档案的电子邮件, 所以寄出前一定要先询问对方. 另外有一点要特别注意, 因为这个档案记录了完整的程式执行状态, 所以里面可能含有各种"机密" (程式可能正在处理私人讯息或机密资料).

"问题出现后我又试着..."

当错误发生之后, 你可以做各种因应的动作. 大部份动作都会让问题更严重. 我有个唸书时期的朋友不小心删掉她所有的Word文件, 她在找专家求救之前试着重装了Word又执行"磁盘重整". 这两个动作对救回档案都没有帮助, 反而把磁盘机内容弄得更乱. 最后就是没有任何档案回复程式能救回她的档案. 如果她把电脑放著不去动, 可能还有点机会.

这样的使用者就像缩在角落的麝香猴: 背紧贴著墙面对死亡威胁时会疯狂地攻击, 因为它觉得有动作总比什么都不做要好. 不过这种作法并不适用于电脑产生的问题.

和麝香猴相反的是羚羊. 当羚羊面对无法预期的事物或害怕时就会定住不动. 它会停下来保持完全静止, 试着不要引起任何注意, 同时思考最佳的因应措施. (如果羚羊有技术支援专线可用, 这时候就会打电话求援.) 一旦决定最安全的做法后, 它就会照着执行.

所以遇到问题时要立即停止所有动作. 不要碰任何按键. 看着萤幕注意是否有任何不寻常的地方, 然后把异常之处记下或抄下来. 再来或许可以小心地按"确定"或"取消", 看哪一个看起来最安全而定. 要试着养成一种直觉反应 - 如果电脑出现预期之外的反应, 什么都不要动.

如果你有办法排除问题(不管是把出问题的程式关掉或是重开电脑), 可以试着让问题再次重现. 程式师喜欢那些能重复产生的问题. 这时候快乐的程式师能更快更有效率地修正问题.

"我认为一定是超光速调变的极化出了问题."

并不是程式师以外的人才会写出烂错误报告. 我所看过最糟糕的错误报告中有些就是程式师写的, 而且有些还是很优秀的师式师.

我曾经和另一个程式师合作, 他一直在寻找自己程式里的错误并试着修正. 每次遇到解不出来的问题时, 就打电话叫我帮忙. 当我问他"哪里出错了?", 他就会回答他目前对问题应如何修正的看法.

如果他的看法正确无误事情就很顺利. 由于他已经把事情完成一半了, 我们就能一起把工作完成. 这时候他的意见很有帮助而且非常有效.

问题是他经常会出错. 这时候他会花时间找出为何程式中某个部份产生错误的资料, 到最后才发现那些资料是正确的, 结果我们花了半小时去查一段完全正确的程式码, 而实际的问题却在别的地方.

我确信他并不会对医生这样做. 大家都不会和医生这样讲话:"医生, 我得了Hydroyoyodyne病(译注:虚构的怪病), 给我开个药吧.". 你应该会说有哪里不舒服, 哪里酸痛哪里起疹, 有没有发烧等等, 然后让医生诊断并开出处方. 否则医生会把你当忧郁症或神经病, 理直气壮地赶你出门.

对程式师也一样. 提供你自己的诊断有时可能有帮助, 不过一定要先叙述症状. 诊断是可有可无的, 绝不能取代症状叙述. 同样的道理, 在错误报告之外附加一份把问题修好的程式码是很有帮助, 不过程式码并不能取代错误报告.

如果程式师要你提供更多资讯, 绝对不要伪造资料! 曾经有人回报一个错误, 我要他试一个我知道不能动的命令. 要他试这个命令, 是因为我想知道它会出现哪一个错误讯息. 知道会传回哪一个错误讯息就等于得到重要的线索. 可是他并没有真的去试, 却直接回信给我说:"不, 那个命令没有用." 我费了好一番功夫才说服他实际去试命令.

用你的聪明智慧帮助程式师是很好. 即使你的推论不对, 程式师也应该心存感谢, 因为至少你已经试着让他们更好过. 不过记得要报告症状, 否则你可能会让他们过得更痛苦.

"真奇怪, 刚刚才出过问题的."

程式师听到"偶发性的错误"一定都会很头大. 能依照某段单纯动作过程产生的错误算是简单的问题. 程式师可以在严密观察的测试环境下重复这些动作, 仔细观察问题发生时的所有细节. 不过很多问题都不是这样的: 有些程式一星期会当一次, 也有些问题很久很久才出现一次, 还有些问题程式师在的时候绝不出现, 等最后期限逼近时却时常发作.

大部份偶发性的错误并不是真正的偶发. 其中多数都有某些逻辑存在. 有些可能是在机器内存不足时才出现, 有些错误可能是因为另一只程式在不对的时点修改一个重要档案, 还有些错误可能只在每小时前30分出现! (我真的遇过这种错误)

如果你能重现错误而程式师不能, 很可能是因为你和程式师的电脑在某个地方有差异, 而这个差异就是问题的原因. 我曾经遇到一个怪问题, 视窗会在萤幕左上角缩成一个小球. 不过只有在800x600的萤幕上才会发生; 在我的1024x768萤幕上完全没有问题.

程式师会想得到你对于问题所知的全部资料. 你可以在另一台机器试看看. 也可以试个两三次看看出问题的频率如何. 如果问题只在你努力工作时才出现, 要展示给别人看时又完全正常, 出错的原因可能是长时间执行或档案太大. 试着记下出错时你正在做的动作, 而且尽可能记下细节. 如果观察到任何模式都要记下来. 你所提供的任何资料多少都有帮助. 即使只是"机率性"的叙述 (比如有执行Emacs时似乎比较容易当), 虽然不能提供指向问题的直接线索, 不过还是可能协助程式师重现问题.

更重要的是, 程式师要确认他们处理的是真正的偶发性问题还是与机器相关的错误. 他们会要知道很多有关你的电脑的细节, 这样才能找出你的电脑和他们的电脑的差异所在. 很多细节会视程式而定, 不过版本号码通常是一定要的. 程式本身的版本, 作业系统的版本, 可能还要包括其他与问题有关的程式的版本号码.

"所以我把磁片加载视窗系统中..."

写得清楚是错误报告的基本. 如果程式师看不懂你的意思, 报告有写等于没写.

我收到全世界来的错误报告. 很多报告来自非英语系地区, 而且很多人为英文写得不好致歉. 通常有为英文不好而致歉的错误报告实际上都非常清楚有用. 写得最含糊不清的报告全都是来自英语系地区, 这些作者认为他们不必写的清楚精确, 我还是能明白其中的意思.

要明确. 如果你可以用不同方法完成同一件事, 就要写出你用的方法. "我选取Load"可能是说"我点选Load"或是 "我按了Alt+L键". 把你做的事说清楚. 有时候这点很重要.

要详细. 宁愿多给资讯而不要少给. 如果你说得太多, 程式师可以略过一些不看. 不过如果你说得太少, 他们就得回来问更多的问题. 我收过一份里面只有一句话的错误报告. 我花了好几个星期才得到足够份量的有用资讯, 因为他的回复每次都只有一个短句子.

要小心代名词. 避免在意义不明确时使用"它"或"视窗"之类的字眼. 考虑以下的状况: "我启动FooApp. 它跑出一个警告视窗. 我试着把它关掉可是它当掉了." 这里并没有明确指明使用者想关掉什么东西. 他究竟要关掉警告视窗还是整个FooApp? 你可以改写成"我启动FooApp, FooApp显示一个警告视窗. 我试图关闭警告视窗, 结果FooApp当掉了." 这些写比较长而且囉嗦, 不过比较清楚也不容易误解.

阅读你写的东西. 自己把报告重新读一遍, 看看有是否够清楚. 如果你有写出了重现问题的步骤列表, 试着照做一遍确定没有漏掉任何步骤.

摘要

一份错误报告的首要目标是要让程式师亲眼看到问题. 如果你不能到他们面前把问题显示出来, 就得提供详细的指示让他们能自己做出来.

万一首要目标无法达成, 程式师没法子自己看到问题发生, 那么错误报告的第二目标就是描述问题状况. 尽量详细叙述每件事. 把看到的东西都写出来, 期望看到的东西也要写出来. 错误讯息也要抄下来, 如果讯息里有数字的话更是不能漏掉.

当你的电脑出现预期之外的反应, 记得什么动作都不要做. 在你冷静之前什么都不要做, 另外不要进行任何有危险性的动作.

如果你自认能力够的话可以尽量尝试自己诊断问题, 不过即使你做了诊断, 还是应该报告问题的症状.

要准备在程式师需要时提供额外的资讯. 如果他们不需要就不会要. 程式师并不会故意刁难. 还有可以把版本号码先准备好, 因为很可能会需要.
要写得清楚明白. 照你的意思去写并且确定意思不会被误解.

最后一点就是要精确. 程式师喜欢精确.

Vixual