做者：SimonTatham 翻譯：Dasn html
引言
爲公衆寫過軟件的人，大概都收到過很拙劣的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。 react
How to Report Bugs Effectively
by Simon Tatham, professional and free-software programmer Introduction Anybody who has written software for public use will probably have received at least one bad bug report. Reports that say nothing ("It doesn't work!"); reports that make no sense; reports that don't give enough information; reports that give wrong information. Reports of problems that turn out to be user error; reports of problems that turn out to be the fault of somebody else's program; reports of problems that turn out to be network failures. There's a reason why technical support is seen as a horrible job to be in, and that reason is bad bug reports. However, not all bug reports are unpleasant: I maintain free software, when I'm not earning my living, and sometimes I receive wonderfully clear, helpful, informative bug reports. In this essay I'll try to state clearly what makes a good bug report. Ideally I would like everybody in the world to read this essay before reporting any bugs to anybody. Certainly I would like everybody who reports bugs to me to have read it. In a nutshell, the aim of a bug report is to enable the programmer to see the program failing in front of them. You can either show them in person, or give them careful and detailed instructions on how to make it fail. If they can make it fail, they will try to gather extra information until they know the cause. If they can't make it fail, they will have to ask you to gather that information for them. In bug reports, try to make very clear what are actual facts ("I was at the computer and this happened") and what are speculations ("I think the problem might be this"). Leave out speculations if you want to, but don't leave out facts. When you report a bug, you are doing so because you want the bug fixed. There is no point in swearing at the programmer or being deliberately unhelpful: it may be their fault and your problem, and you might be right to be angry with them, but the bug will get fixed faster if you help them by supplying all the information they need. Remember also that if the program is free, then the author is providing it out of kindness, so if too many people are rude to them then they may stop feeling kind. "It doesn't work." Give the programmer some credit for basic intelligence: if the program really didn't work at all, they would probably have noticed. Since they haven't noticed, it must be working for them. Therefore, either you are doing something differently from them, or your environment is different from theirs. They need information; providing this information is the purpose of a bug report. More information is almost always better than less. Many programs, particularly free ones, publish their list of known bugs. If you can find a list of known bugs, it's worth reading it to see if the bug you've just found is already known or not. If it's already known, it probably isn't worth reporting again, but if you think you have more information than the report in the bug list, you might want to contact the programmer anyway. They might be able to fix the bug more easily if you can give them information they didn't already have. This essay is full of guidelines. None of them is an absolute rule. Particular programmers have particular ways they like bugs to be reported. If the program comes with its own set of bug-reporting guidelines, read them. If the guidelines that come with the program contradict the guidelines in this essay, follow the ones that come with the program! If you are not reporting a bug but just asking for help using the program, you should state where you have already looked for the answer to your question. ("I looked in chapter 4 and section 5.2 but couldn't find anything that told me if this is possible.") This will let the programmer know where people will expect to find the answer, so they can make the documentation easier to use. "Show me." One of the very best ways you can report a bug is by showing it to the programmer. Stand them in front of your computer, fire up their software, and demonstrate the thing that goes wrong. Let them watch you start the machine, watch you run the software, watch how you interact with the software, and watch what the software does in response to your inputs. They know that software like the back of their hand. They know which parts they trust, and they know which parts are likely to have faults. They know intuitively what to watch for. By the time the software does something obviously wrong, they may well have already noticed something subtly wrong earlier which might give them a clue. They can observe everything the computer does during the test run, and they can pick out the important bits for themselves. This may not be enough. They may decide they need more information, and ask you to show them the same thing again. They may ask you to talk them through the procedure, so that they can reproduce the bug for themselves as many times as they want. They might try varying the procedure a few times, to see whether the problem occurs in only one case or in a family of related cases. If you're unlucky, they may need to sit down for a couple of hours with a set of development tools and really start investigating. But the most important thing is to have the programmer looking at the computer when it goes wrong. Once they can see the problem happening, they can usually take it from there and start trying to fix it. "Show me how to show myself." This is the era of the Internet. This is the era of worldwide communication. This is the era in which I can send my software to somebody in Russia at the touch of a button, and he can send me comments about it just as easily. But if he has a problem with my program, he can't have me standing in front of it while it fails. "Show me" is good when you can, but often you can't. If you have to report a bug to a programmer who can't be present in person, the aim of the exercise is to enable them to reproduce the problem. You want the programmer to run their own copy of the program, do the same things to it, and make it fail in the same way. When they can see the problem happening in front of their eyes, then they can deal with it. So tell them exactly what you did. If it's a graphical program, tell them which buttons you pressed and what order you pressed them in. If it's a program you run by typing a command, show them precisely what command you typed. Wherever possible, you should provide a verbatim transcript of the session, showing what commands you typed and what the computer output in response. Give the programmer all the input you can think of. If the program reads from a file, you will probably need to send a copy of the file. If the program talks to another computer over a network, you probably can't send a copy of that computer, but you can at least say what kind of computer it is, and (if you can) what software is running on it. "Works for me. So what goes wrong?" If you give the programmer a long list of inputs and actions, and they fire up their own copy of the program and nothing goes wrong, then you haven't given them enough information. Possibly the fault doesn't show up on every computer; your system and theirs may differ in some way. Possibly you have misunderstood what the program is supposed to do, and you are both looking at exactly the same display but you think it's wrong and they know it's right. So also describe what happened. Tell them exactly what you saw. Tell them why you think what you saw is wrong; better still, tell them exactly what you expected to see. If you say "and then it went wrong", you have left out some very important information. If you saw error messages then tell the programmer, carefully and precisely, what they were. They are important! At this stage, the programmer is not trying to fix the problem: they're just trying to find it. They need to know what has gone wrong, and those error messages are the computer's best effort to tell you that. Write the errors down if you have no other easy way to remember them, but it's not worth reporting that the program generated an error unless you can also report what the error message was. In particular, if the error message has numbers in it, do let the programmer have those numbers. Just because you can't see any meaning in them doesn't mean there isn't any. Numbers contain all kinds of information that can be read by programmers, and they are likely to contain vital clues. Numbers in error messages are there because the computer is too confused to report the error in words, but is doing the best it can to get the important information to you somehow. At this stage, the programmer is effectively doing detective work. They don't know what's happened, and they can't get close enough to watch it happening for themselves, so they are searching for clues that might give it away. Error messages, incomprehensible strings of numbers, and even unexplained delays are all just as important as fingerprints at the scene of a crime. Keep them! If you are using Unix, the program may have produced a core dump. Core dumps are a particularly good source of clues, so don't throw them away. On the other hand, most programmers don't like to receive huge core files by e-mail without warning, so ask before mailing one to anybody. Also, be aware that the core file contains a record of the complete state of the program: any "secrets" involved (maybe the program was handling a personal message, or dealing with confidential data) may be contained in the core file. "So then I tried . . ." There are a lot of things you might do when an error or bug comes up. Many of them make the problem worse. A friend of mine at school deleted all her Word documents by mistake, and before calling in any expert help, she tried reinstalling Word, and then she tried running Defrag. Neither of these helped recover her files, and between them they scrambled her disk to the extent that no Undelete program in the world would have been able to recover anything. If she'd only left it alone, she might have had a chance. Users like this are like a mongoose backed into a corner: with its back to the wall and seeing certain death staring it in the face, it attacks frantically, because doing something has to be better than doing nothing. This is not well adapted to the type of problems computers produce. Instead of being a mongoose, be an antelope. When an antelope is confronted with something unexpected or frightening, it freezes. It stays absolutely still and tries not to attract any attention, while it stops and thinks and works out the best thing to do. (If antelopes had a technical support line, it would be telephoning it at this point.) Then, once it has decided what the safest thing to do is, it does it. When something goes wrong, immediately stop doing anything. Don't touch any buttons at all. Look at the screen and notice everything out of the ordinary, and remember it or write it down. Then perhaps start cautiously pressing "OK" or "Cancel", whichever seems safest. Try to develop a reflex reaction - if a computer does anything unexpected, freeze. If you manage to get out of the problem, whether by closing down the affected program or by rebooting the computer, a good thing to do is to try to make it happen again. Programmers like problems that they can reproduce more than once. Happy programmers fix bugs faster and more efficiently. "I think the tachyon modulation must be wrongly polarised." It isn't only non-programmers who produce bad bug reports. Some of the worst bug reports I've ever seen come from programmers, and even from good programmers. I worked with another programmer once, who kept finding bugs in his own code and trying to fix them. Every so often he'd hit a bug he couldn't solve, and he'd call me over to help. "What's gone wrong?" I'd ask. He would reply by telling me his current opinion of what needed to be fixed. This worked fine when his current opinion was right. It meant he'd already done half the work and we were able to finish the job together. It was efficient and useful. But quite often he was wrong. We would work for some time trying to figure out why some particular part of the program was producing incorrect data, and eventually we would discover that it wasn't, that we'd been investigating a perfectly good piece of code for half an hour, and that the actual problem was somewhere else. I'm sure he wouldn't do that to a doctor. "Doctor, I need a prescription for Hydroyoyodyne." People know not to say that to a doctor: you describe the symptoms, the actual discomforts and aches and pains and rashes and fevers, and you let the doctor do the diagnosis of what the problem is and what to do about it. Otherwise the doctor dismisses you as a hypochondriac or crackpot, and quite rightly so. It's the same with programmers. Providing your own diagnosis might be helpful sometimes, but always state the symptoms. The diagnosis is an optional extra, and not an alternative to giving the symptoms. Equally, sending a modification to the code to fix the problem is a useful addition to a bug report but not an adequate substitute for one. If a programmer asks you for extra information, don't make it up! Somebody reported a bug to me once, and I asked him to try a command that I knew wouldn't work. The reason I asked him to try it was that I wanted to know which of two different error messages it would give. Knowing which error message came back would give a vital clue. But he didn't actually try it - he just mailed me back and said "No, that won't work". It took me some time to persuade him to try it for real. Using your intelligence to help the programmer is fine. Even if your deductions are wrong, the programmer should be grateful that you at least tried to make their life easier. But report the symptoms as well, or you may well make their life much more difficult instead. "That's funny, it did it a moment ago." Say "intermittent fault" to any programmer and watch their face fall. The easy problems are the ones where performing a simple sequence of actions will cause the failure to occur. The programmer can then repeat those actions under closely observed test conditions and watch what happens in great detail. Too many problems simply don't work that way: there will be programs that fail once a week, or fail once in a blue moon, or never fail when you try them in front of the programmer but always fail when you have a deadline coming up. Most intermittent faults are not truly intermittent. Most of them have some logic somewhere. Some might occur when the machine is running out of memory, some might occur when another program tries to modify a critical file at the wrong moment, and some might occur only in the first half of every hour! (I've actually seen one of these.) Also, if you can reproduce the bug but the programmer can't, it could very well be that their computer and your computer are different in some way and this difference is causing the problem. I had a program once whose window curled up into a little ball in the top left corner of the screen, and sat there and sulked. But it only did it on 800x600 screens; it was fine on my 1024x768 monitor. The programmer will want to know anything you can find out about the problem. Try it on another machine, perhaps. Try it twice or three times and see how often it fails. If it goes wrong when you're doing serious work but not when you're trying to demonstrate it, it might be long running times or large files that make it fall over. Try to remember as much detail as you can about what you were doing to it when it did fall over, and if you see any patterns, mention them. Anything you can provide has to be some help. Even if it's only probabilistic (such as "it tends to crash more often when Emacs is running"), it might not provide direct clues to the cause of the problem, but it might help the programmer reproduce it. Most importantly, the programmer will want to be sure of whether they're dealing with a true intermittent fault or a machine-specific fault. They will want to know lots of details about your computer, so they can work out how it differs from theirs. A lot of these details will depend on the particular program, but one thing you should definitely be ready to provide is version numbers. The version number of the program itself, and the version number of the operating system, and probably the version numbers of any other programs that are involved in the problem. "So I loaded the disk on to my Windows . . ." Writing clearly is essential in a bug report. If the programmer can't tell what you meant, you might as well not have said anything. I get bug reports from all around the world. Many of them are from non-native English speakers, and a lot of those apologise for their poor English. In general, the bug reports with apologies for their poor English are actually very clear and useful. All the most unclear reports come from native English speakers who assume that I will understand them even if they don't make any effort to be clear or precise. * Be specific. If you can do the same thing two different ways, state which one you used. "I selected Load" might mean "I clicked on Load" or "I pressed Alt-L". Say which you did. Sometimes it matters. * Be verbose. Give more information rather than less. If you say too much, the programmer can ignore some of it. If you say too little, they have to come back and ask more questions. One bug report I received was a single sentence; every time I asked for more information, the reporter would reply with another single sentence. It took me several weeks to get a useful amount of information, because it turned up one short sentence at a time. * Be careful of pronouns. Don't use words like "it", or references like "the window", when it's unclear what they mean. Consider this: "I started FooApp. It put up a warning window. I tried to close it and it crashed." It isn't clear what the user tried to close. Did they try to close the warning window, or the whole of FooApp? It makes a difference. Instead, you could say "I started FooApp, which put up a warning window. I tried to close the warning window, and FooApp crashed." This is longer and more repetitive, but also clearer and less easy to misunderstand. * Read what you wrote. Read the report back to yourself, and see if you think it's clear. If you have listed a sequence of actions which should produce the failure, try following them yourself, to see if you missed a step. Summary * The first aim of a bug report is to let the programmer see the failure with their own eyes. If you can't be with them to make it fail in front of them, give them detailed instructions so that they can make it fail for themselves. * In case the first aim doesn't succeed, and the programmer can't see it failing themselves, the second aim of a bug report is to describe what went wrong. Describe everything in detail. State what you saw, and also state what you expected to see. Write down the error messages, especially if they have numbers in. * When your computer does something unexpected, freeze. Do nothing until you're calm, and don't do anything that you think might be dangerous. * By all means try to diagnose the fault yourself if you think you can, but if you do, you should still report the symptoms as well. * Be ready to provide extra information if the programmer needs it. If they didn't need it, they wouldn't be asking for it. They aren't being deliberately awkward. Have version numbers at your fingertips, because they will probably be needed. * Write clearly. Say what you mean, and make sure it can't be misinterpreted. * Above all, be precise. Programmers like precision. Disclaimer: I've never actually seen a mongoose or an antelope. My zoology may be inaccurate. $Id: bugs.html 8168 2008-09-08 18:03:28Z simon $ Copyright © 1999 Simon Tatham. This document is OpenContent. You may copy and use the text under the terms of the OpenContent Licence.