作者：developerHaoz
鏈接：https://www.jianshu.com/p/6c21bbaebb9d
原文：https://www.chiark.greenend.org.uk/~sgtatham/bugs-tw.html
概述
寫過開源軟件的人，大都收到過至少一個很糟糕的 bug 報告，例如
- 直接說軟件不好用
- 報告的內容毫無意義
- 沒有提供足夠的信息
- 給出了錯誤的信息
- 問題是由於用戶的過失產生的
- 問題是由於其他程序的錯誤而產生的
- 問題是由於網絡錯誤而產生的
這也是「技術支持」被視為一個可怕工作的原因。然而，並不是所有的 bug 報告都是讓人不愉快的。我一直在沒賺錢的時候維護開源軟件，有時候會收到一些非常清晰的、有幫助的、內容豐富的 bug 報告。
在這篇文章中，我將盡量說清楚如何去寫一個好的 bug 報告。我非常希望所有人在報告一個 bug 給其他人之前先看看這篇文章。當然我也希望其他人在給我提 bug 之前已經閱讀過這篇文章。
簡單地說，報告 bug 的目的是為了讓程序員看到程序的錯誤。你可以親自示範，也可以給出能夠「重現程序錯誤」的詳細、具體的操作說明。如果程序真的出錯了，程序員將會試著收集額外信息直到找到錯誤的原因。如果程序並沒有出錯，他們可能會讓你繼續收集更多的信息給他們。
在 bug 報告中，要弄清楚事實（“ 我在電腦上出現了這個問題 ”）和猜測（“ 我覺得這個錯誤應該是... ”）的區別，如果你願意的話，可以省略猜測，但千萬不要省略事實。
當你在報告 bug 的時候，一定是希望 bug 能夠得到修復。所以針對程序員的不好的言語（甚至謾罵）都是沒意義的。bug 的產生可能是他們的錯，也可能是你自己的問題，或許你有權利對他們發火，但是如果你給他們提供更多有用信息的話，bug 可能會修復的更快。而且請記住：如果軟件是免費的話，作者提供了這個軟件已經是出於好心，如果太多人對他們無禮的話，他們可能就要收回這種好心了。
一、程序不好用
程序員並不是弱智，如果程序真的一點都不好用的話，他們不可能沒有察覺到。既然他們沒有察覺到，那肯定是因為程序對於他們是有幫助的。因此，可能是因為你的操作跟他們不一樣，或者你的環境跟他們不一樣。他們需要更多的信息，提供這些信息是 bug 報告的主要目的。信息總是越多越好。
很多程序，特別是開源程序，會提供一個「已知 bug 的列表」，如果你發現這個 bug
在列表裡面有的話，那你有必要好好閱讀一下，沒必要再報告一次這個 bug，但是如果你覺得你掌握了比這個 bug 列表更多信息的話，那你一定要與程序員進行聯繫，如果你提供了一些他們之前沒有掌握的信息的話，他們將會更容易地修改這些 bug.
這篇文章談的都是一些指導指南，並不是說他們就一定是要嚴格恪守的。不同的程序員喜歡不同的 bug 報告方式。如果程序裡面附帶了自己的 bug 報告指南的話，請好好閱讀他們。如果程序中的指導指南與本文中的指導指南有矛盾的話，請遵循程序中附帶的指導指南！
如果你不是報告 bug，而是想要尋求幫助的話，你應該說明你曾經到哪尋找問題的答案（例如，“ 我看了第四章和第五章第二節，但是找不到解決問題的方法 ”），這會讓程序員知道人們期望找到答案的地方，然後他們能讓文檔變得更加容易使用。
二、演示給我看
報告 bug 的最好方式之一就是演示給程序員看。讓他們站在你的電腦前面，運行他們的程序，然後演示出錯的地方。讓他們看你是如何啟動機器、運行軟件、操作軟件、以及程序對於你的輸入所作出的反應。
他們對於自己寫的軟件很瞭解，知道哪些部分很安全，知道哪些可能會出現問題。他們本能知道應該注意些什麼。在程序真的出錯之前，他們可能已經察覺到不對勁的地方，這些都會給他們一些線索。他們能觀察在測試運行期間電腦做的每一件事，然後挑選出他們認為有用的信息。
這可能還不夠。也許他們會覺得需要更多的信息，然後讓你重新演示一遍。他們可能會在這期間跟你交流一下，以便在他們需要的時候能夠重現 bug. 他們可能會試著改變一些操作，以查看問題是個別問題還是一類的問題。如果你比較不走運的話，他們可能會坐下來幾個小時，拿出一整套開發工具，好好的研究這個問題。但是最重要的是在程序出錯的時候讓程序員就在電腦旁。一旦他們看到問題發生，他們通常可以找到問題所在並開始嘗試解決他們。
三、告訴我該怎麼做
現在是網絡時代，是信息交流的時代，是我們能夠點擊按鈕發送軟件給俄羅斯朋友的時代，而且他們也能夠很方便地評價這個軟件。但是如果他發現我的軟件存在問題的話，我不可能在他旁邊。「演示」是一個很好的方法，但是很多時候都做不到。
如果你必須報告這個 bug，但是程序員又不在現場的話，那你就要想辦法重現這個問題，當他們親眼看到這個問題發生的時候，他們就會處理它了。
所以，你要告訴他們你做了什麼。如果是一個圖形程序，那你需要告訴他們你所點擊的按鈕，以及你點擊它們的順序。如果是一個命令行程序的話，請精確地告訴他們你輸入了什麼命令。除此之外，你還應該儘可能詳細地提供你輸入的命令以及計算機輸出的響應。
把你能想到的所有輸入的方式告訴程序員。如果程序需要讀取一個文件的話，你可能需要發送文件的副本給他們。如果程序是需要跟另外一臺電腦進行網絡通信的話，你可能無法發送電腦的副本給他們，但是你至少需要告訴他們電腦的型號，以及安裝的軟件。
四、我這裡很正常啊，哪裡出錯了？
如果你給程序員提供了很長的輸入和操作列表，然後他們運行了自己的程序副本之後並沒有發現問題，很有可能是你沒有提供足夠的信息。可能這個錯誤不會出現在每一臺電腦上面，你的電腦系統可能和他們的電腦在某些方面不一樣。也有可能是你誤解了程序怎樣顯示才是對的，例如你們可能看著同樣的顯示，但是你覺得這是有問題的，但是程序員卻認為是正確的。
所以也要描述究竟發生了什麼，告訴他們你看到了什麼東西以及為什麼你覺得你看到的東西是錯誤的。最好再告訴他們你希望看到的結果是什麼。如果你只是說：“ 程序出錯了 ”，那可能將會遺漏非常重要的信息。
如果你看到了錯誤的信息，請仔細、精確的告訴了程序員，這很重要！在這種情況下，程序員只需要修正錯誤，而不用去找錯誤。他們需要知道哪裡出錯了，而電腦顯示的錯誤信息正好能夠幫助他們。如果你沒有更簡單的方式去記住這些錯誤的話，請把這些錯誤寫下來。只報告「程序出現了一個錯誤」是沒有意義的，你應該同時將錯誤信息也一塊報告上來。
特別是，當錯誤信息含有數字時，一定要把這些數字告訴程序員。可能你並不看出這些數字代表什麼意思，但不意味著它沒有任何意義。數字裡麵包含了很多程序員可以讀取的各種信息，而且可能包括重要的線索。用數字來代表錯誤信息是因為計算機很難用語言來描述它發生的問題，用這種方式告訴你錯誤的所在是最好的辦法。
在這種情況下，程序員能夠高效地完成排錯工作。他們不知道發生了什麼，也不能近距離的觀察發生的事情，所以他們會盡可能地尋找有用的線索。錯誤的信息、令人費解的數字串，甚至是無法解釋的延遲都相當重要，請保留它們。
如果你們使用 Unix 系統，程序可能會產生一個內核輸出。內核輸出是線索的重要來源，所以請不要丟掉他們。另一方面，大部分的程序員都不喜歡通過郵件來接收大的內核文件，所以在發郵件給他們之前，最好先問一下。還有一點要注意一下，內核輸出文件記錄了完整的程序運行狀態：也就是說任何「秘密」（可能程序正在處理私人信息，或者在處理秘密數據）都可能包含在內核文件中。
五、出了問題後，我做了...
當錯誤或者 bug 出現的時候，你可能會做這些事情。但大多數會讓問題變得更加嚴重。我有一個朋友在學校誤刪了她所有的 Word 文檔，在尋求專業人員的幫助之前，她試圖重裝 Word，然後她試著運行 Defrag. 這些操作對於恢復她的文件毫無作用，而且還會打亂磁盤的文件區塊，所以世界上沒有任何反刪除的軟件可以恢復她的文件，如果她不那樣做的話，還有一絲希望。
用戶這樣的行為就像是一隻被逼到牆角的鼬，背靠牆壁，面對死亡的來臨，瘋狂的攻擊，因為他們覺得做點什麼總比什麼都不做要強，但這並不適合計算機產生的問題。
不要做一隻鼬，而要像羚羊一樣。當羚羊面對它們沒有想到的情況或者受到驚嚇的時候，它們會一動不動，保持絕對靜止，儘量不吸引任何注意力，然後停下來思考和制定最好的應對措施。當它們找到了最安全的方案，便會去做。
當程序出問題的時候，請停止做任何事情。不要去按任何按鈕，仔細看屏幕，然後觀察那些不正常的事情，記住並記錄好。當它看起來比較安全的時候，或許可以開始小心地點擊「OK」或者「Cancel」。試著養成一種習慣：「當一臺電腦出了問題，先不要進行任何操作」 。
如果你想解決這個問題，關掉出了問題的程序或者重啟電腦都不是一個好的方法，最好的解決方法是重現這個問題。程序員們喜歡可以被重現的問題，快樂的程序源碼能夠更快更有效率地修復 bug.
六、描述症狀很重要
並不是只有非程序員才會寫出很糟糕的 bug 報告。我也看過很多很差的 bug 報告出自程序員之手，有些甚至出自很優秀的程序員。
我曾經跟另一個程序員一起工作，他一直在找代碼中的 bug，經常找到一些他自己解決不了的 bug，然後讓我幫忙解決。“ 出什麼問題了？ ” 我問。然而他的回答卻總是一些關於他對這些 bug 的意見。
如果他的意見是正確的話，那確實是一件好事。意味著他已經完成了一半的工作量，並且我們可以一起完成另一半的工作，這是非常有效率並且是有用的。
但是很多時候，他的觀點都是錯的。我們需要花很多的時間去尋找產生錯誤的地方，但是最後我們經常會花了半個鍾在原本正確的代碼中尋找錯誤，而實際上問題出在其他地方。我敢確定他肯定不敢對醫生這麼做。“ 醫生，我得了一種怪病，給我開個方子吧 ”。 人們知道不應該對醫生說這些。我們應該描述哪裡不舒服、哪裡疼，然後讓醫生來判斷問題的所在，以及應該怎樣進行治療，否則醫生將會把你當成「神經病」。
程序員也是這樣，提供自己的判斷可能會有所幫助，但最好還是把「症狀」說出來。判斷是可有可無的，但是「症狀」一定要說出來。同樣，在 bug 報告中附上一份修改後的源代碼是一個很好的補充，但並不是描述「症狀」的替代品。
如果一個程序員讓你提供更多的信息，請不要應付。以前有一個人向我報告了一個 bug，然後我讓他去敲一個命令，我知道這個命令不好用，但我想看看程序會返回一個什麼錯誤（這是很重要的線索），但他並沒有試。他只是發郵件跟我說：“ 那並沒有作用 ”。然後我花了很多的時間去說服他試一次那個命令。
使用你的聰明才智來幫助程序員是一件很美好的事情。即使你的推論是錯誤的，程序員也應該感激你，至少你想去幫助他們，讓他們的生活變得更加輕鬆。不過，也不要忘了報告「症狀」，否則只會讓事情變得更加糟糕。
七、真是奇怪，剛才還有問題，現在就好了
「間接性錯誤」確實很讓程序員發愁。進行一系列簡單的操作，然後就能產生錯誤的問題是很容易解決的。程序員可以在一個便於觀察的情況下重複那些操作，然後觀察它們究竟發生了什麼。但是很多問題在這種情況下是不能解決的。例如：每星期出一次錯，偶爾出一次錯，或者在程序員面前從沒有出錯過，但經常會在截止日期快到的時候出現。
大多數的「間歇性故障」並不是真正的「間歇」。他們中大多數跟某些地方是有聯繫的。有一些錯誤是機器內存溢出造成的，有一些因為另一個程序在不恰當的場合修改重要文件造成的，還有一些發生在每個小時的前半個小時（我確實遇到過這些問題）。
另外，如果你可以重現錯誤，但程序員卻不行，那麼你的電腦和他們的電腦可能在某些地方是不一樣的，而這個區別就是造成這個問題的原因。我曾經寫過一個程序，它的窗口會縮成一個小球懸浮在屏幕的左上角，它在別的機器上只能在分辨率為 800 × 600 時工作，但是在我的計算機上卻能在 1024 × 768 的分辨率下工作。
程序員很想知道與你發現的問題相關的所有事情。如果可以的話，請在另外一臺機器上試一次、兩次甚至三次，觀察它是不是經常出錯。如果問題出現在你做了一系列嚴謹的工作之後，而且並不是你想演示就能夠演示出來的話，那很可能是長時間的運行或者是處理大文件導致出錯的。程序出錯的時候，請儘可能記住你之前做了什麼操作，如果你看到了什麼圖形，也記得提醒一下。你提供的信息都是有幫助的。即使它只是「概率性」的出現（比如當 Emacs 運行時他往往會更頻繁地崩潰），這可能不會提供問題原因的直接線索，但有助於程序員重現它。
最重要的是，程序員將要確定他們是否在處理真正的間歇性故障或者是機器特定的故障。他們會想知道很多關於你電腦的細節，由此來弄清楚你的電腦和他們電腦之間的區別。很多這些細節都取決於特定的程序，但是有一件事你應該準備好，那就是「版本號」，程序本身的版本號、操作系統的版本號以及可能會跟問題有關的其他程序的版本號。
八、我把磁盤裝進了 Windows...
在 bug 報告中，將問題描述清楚是必要的。如果程序員不能理解你說的是什麼意思，那你跟沒說是一樣的。
我收到的 bug 報告來自世界各地。有很多是來自非英語國家的。他們通常會因為他們自己英文不好表示歉意。但總的來說，他們的 bug 報告還是非常清晰而且有用的。幾乎所有最不清楚的報告都來自母語為英語的人，他們以為只要隨便說說，就能讓程序員明白他們的問題。
- 請明確點：如果你能夠使用兩種不同的方式，請說明你使用了哪一種。例如，我選擇加載可能意味著「我點擊加載」或「我按了 Alt + L」，說清楚你究竟做了什麼，是很重要的。
- 請詳細點：信息越多越好，如果你說了很多，程序員可以忽略掉其中的一些東西，但是如果你說的太少的話，程序員就得回過頭來問你更多的問題。我曾經收到過一個「只有一句話的 bug 報告」。每次問他更多事情時，他只是簡單地回覆一句話。然後整整花了我好幾個星期才獲取到足夠的信息。
- 慎用代詞：不要使用像「it」或者「the window」之類的詞語，當它們指代不明的時候不要用。舉個例子，“ 我開啟了 FooApp，它彈出了一個警告窗口，我試著關閉它，然後他就崩潰了 ”。用戶究竟試著關閉什麼，這並不清楚。他們是試著關閉警告窗口，還是整個 FooApp？你可以這樣說 “ 我開啟了 FooApp，它彈出一個警告窗口，我試圖關閉警告窗口，然後 FooApp 就崩潰了。” 這雖然比較長而且比較囉嗦，但是卻比較清晰而且不容易產生誤會。
- 仔細檢查：請仔細閱讀你自己寫的 bug 報告，你覺得它是否清晰？如果你列出了一系列可能會導致失敗的操作，請嘗試自行跟蹤，看看你是否遺漏了哪個步驟。
總結
- bug 報告最重要的就是讓程序員親眼看到錯誤，如果你不能在他們面前讓程序出錯，那就給他們具體的細節說明，讓他們能重現錯誤。
- 如果最重要的目標沒有成功，程序員沒法親眼看到錯誤，那麼 bug 報告的第二個目標就是去描述出現了什麼問題。描述所有的細節，說出你看到的所有信息，並說出你期望看到的。請記錄下錯誤信息，特別是「錯誤數字」。
- 如果你的電腦出現什麼意想不到的事情，不要動。在你冷靜之前，請不要作出任何你認為可能會很危險的事情。
- 如果你認為可以的話，請儘量自己先診斷錯誤，如果你這樣做的話，你還應該將「症狀」報告給程序員。
- 如果程序員需要的話，請提供額外的信息，如果他們不需要的話，他們是不會要求的，他們不會故意為難自己。如果你手中有版本號的話，很可能是必要的。
- 請表達清楚問題所在，並確保他們不會被誤解。
- 總的來說，請儘可能「精確」，因為程序員喜歡精確。
閱讀更多 程序員聖經 的文章
