如何有效地報告Bug

英文原文：Simon Tatham，編譯：Dasn

引言

爲公衆寫過軟件的人，大概都收到過很拙劣的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重現，而程序員不能，那頗有多是他們的計算機和您的計算機在某些地方是不一樣的，這種不一樣引發了問題。我曾寫過一個程序，它的窗口能夠蜷縮成一個小球呆在屏幕的左上角，它在別的計算機上只能在 800×600 的解析度工做，可是在個人機器上卻能夠在 1024×768 下工做。

程序員想要了解任何與您發現的問題相關的事情。有可能的話您到另外一臺機器上試試，多試幾回，兩次，三次，看看問題是否是常常發生。若是問題出如今您 進行了一系列操做以後，不是您想讓它出現它就會出現，這就有多是長時間的運行或處理大文件所致使的錯誤。程序崩潰的時候，您要儘量的記住您都作了些什 麼，而且若是您看到任何圖形,也別忘了提一下。您提供的任何事情都是有幫助的。即便只是歸納性的描述（例如：當後臺有EMACS運行時，程序經常出錯）， 這雖然不能提供致使問題的直接線索，可是可能幫助程序員重現問題。

最重要的是：程序員想要肯定他們正在處理的是一個真正的「間歇性錯誤」呢，仍是一個在另外一類特定的計算機上纔出現的錯誤。他們想知道有關您計算機的 許多細節，以便了解您的機器與他們的有什麼不一樣。有許多細節都依仗特定的程序，可是有一件東西您必定要提供——版本號。程序的版本、操做系統的版本以及與 問題有關的程序的版本。

 

「我把磁盤裝進了 Windows……」

表意清楚在一份bug報告裏是最基本的要求。若是程序員不知道您說的是什麼意思，那您就跟沒說同樣。我收到的bug報告來自世界各地，有許可能是來自 非英語國家，他們一般爲本身的英文很差而表示歉意。總的來講，這些用戶發來的bug報告一般是清晰並且有用的。幾乎全部不清晰的bug報告都是來自母語是 英語的人，他們老是覺得只要本身隨便說說，程序員就能明白。

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

詳細。信息寧多毋少！若是您說了不少，程序員能夠略去一部分，但是若是您說的太少，他們就不得不回過頭再去問您一些問題。有一次我收到了一份bug報告只有一句話，每一次我問他更多事情時，他每次的回覆都是一句話，因而我花了幾個星期的時間才獲得了有用的信息。

慎用代詞。諸如「它」，「窗體」這些詞，當它們指代不清晰的時候不要用。來看看這句話：「我運行了FooApp，它彈出一個警告 窗口，我試着關掉它，它就崩潰了。」這種表述並不清晰，用戶究竟關掉了哪一個窗口？是警告窗口仍是整個FooApp程序？您能夠這樣說，「我運行 FooApp程序時彈出一個警告窗口，我試着關閉警告窗口，FooApp崩潰了。」這樣雖然羅嗦點，可是很清晰不容易產生誤解。

檢查。從新讀一遍您寫的bug報告，您以爲它是否清晰？若是您列出了一系列能致使程序出錯的操做，那麼照着作一遍，看看您是否是漏寫了一步。

 

小結：

bug報告的首要目的是讓程序員親眼看到錯誤。若是您不能親自作給他們看，給他們能使程序出錯的詳細的操做步驟。

若是首要目的不能達成，程序員不能看到程序出錯。這就須要bug報告的第二個目的來描述程序的什麼地方出毛病了。詳細的描述每一件事情：您看到了什麼，您想看到什麼，把錯誤消息記下來，尤爲是「錯誤消息號」。

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

儘可能試着本身「診斷」程序出錯的緣由（若是您認爲本身能夠的話）。即便作出了「診斷」，您仍然應該報告「症狀」。

若是程序員須要，請準備好額外的信息。若是他們不須要，就不會問您要。他們不會故意爲難本身。您手頭上必定要有程序的版本號，它極可能是必需品。

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

總的來講，最重要的是要作到精確。程序員喜歡精確。