引言

為公眾寫過軟體的人，大概都收到過很拙劣的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重現，而程式設計師不能，那很有可能是他們的計算機和您的計算機在某些地方是不同的，這種不同引起了問題。我曾寫過一個程式，它的視窗可以蜷縮成一個小球呆在螢幕的左上角，它在別的計算機上只能在 800×600 的解析度工作，但是在我的機器上卻可以在 1024×768 下工作。

程式設計師想要了解任何與您發現的問題相關的事情。有可能的話您到另一臺機器上試試，多試幾次，兩次，三次，看看問題是不是經常發生。如果問題出現在您進行了一系列操作之後，不是您想讓它出現它就會出現，這就有可能是長時間的執行或處理大檔案所導致的錯誤。程式崩潰的時候，您要儘可能的記住您都做了些什麼，並且如果您看到任何圖形,也別忘了提一下。您提供的任何事情都是有幫助的。即使只是概括性的描述（例如：當後臺有EMACS執行時，程式常常出錯），這雖然不能提供導致問題的直接線索，但是可能幫助程式設計師重現問題。

最重要的是：程式設計師想要確定他們正在處理的是一個真正的“間歇性錯誤”呢，還是一個在另一類特定的計算機上才出現的錯誤。他們想知道有關您計算機的許多細節，以便了解您的機器與他們的有什麼不同。有許多細節都依仗特定的程式，但是有一件東西您一定要提供——版本號。程式的版本、作業系統的版本以及與問題有關的程式的版本。

“我把磁碟裝進了 Windows……”

表意清楚在一份bug報告裡是最基本的要求。如果程式設計師不知道您說的是什麼意思，那您就跟沒說一樣。我收到的bug報告來自世界各地，有許多是來自非英語國家，他們通常為自己的英文不好而表示歉意。總的來說，這些使用者發來的bug報告通常是清晰而且有用的。幾乎所有不清晰的bug報告都是來自母語是英語的人，他們總是以為只要自己隨便說說，程式設計師就能明白。

精確。如果做相同的事情有兩種方法，請說明您用的是哪一種。例如：“我選擇了‘載入’”，可能意味著“我用滑鼠點選‘載入’”或“我按下了‘ALT+L’”，說清楚您用了哪種方法，有時候這也有關係。

詳細。資訊寧多毋少！如果您說了很多，程式設計師可以略去一部分，可是如果您說的太少，他們就不得不回過頭再去問您一些問題。有一次我收到了一份bug報告只有一句話，每一次我問他更多事情時，他每次的回覆都是一句話，於是我花了幾個星期的時間才得到了有用的資訊。

慎用代詞。諸如“它”，“窗體”這些詞，當它們指代不清晰的時候不要用。來看看這句話：“我運行了FooApp，它彈出一個警告視窗，我試著關掉它，它就崩潰了。”這種表述並不清晰，使用者究竟關掉了哪個視窗？是警告視窗還是整個FooApp程式？您可以這樣說，“我執行FooApp程式時彈出一個警告視窗，我試著關閉警告視窗，FooApp崩潰了。”這樣雖然羅嗦點，但是很清晰不容易產生誤解。

檢查。重新讀一遍您寫的bug報告，您覺得它是否清晰？如果您列出了一系列能導致程式出錯的操作，那麼照著做一遍，看看您是不是漏寫了一步。

小結：

bug報告的首要目的是讓程式設計師親眼看到錯誤。如果您不能親自做給他們看，給他們能使程式出錯的詳細的操作步驟。

如果首要目的不能達成，程式設計師不能看到程式出錯。這就需要bug報告的第二個目的來描述程式的什麼地方出毛病了。詳細的描述每一件事情：您看到了什麼，您想看到什麼，把錯誤訊息記下來，尤其是“錯誤訊息號”。

當您的計算機做了什麼您料想不到的事，不要動！在您平靜下來之前什麼都別做。不要做您認為不安全的事。

儘量試著自己“診斷”程式出錯的原因（如果您認為自己可以的話）。即使做出了“診斷”，您仍然應該報告“症狀”。

如果程式設計師需要，請準備好額外的資訊。如果他們不需要，就不會問您要。他們不會故意為難自己。您手頭上一定要有程式的版本號，它很可能是必需品。

表述清楚，確保您的意思不能被曲解。

總的來說，最重要的是要做到精確。程式設計師喜歡精確。