作者：Simon Tatham 專業的自由軟件程序員
翻譯：Dasn
原文鏈接/不同語言版本
十分有用的一篇文章，爲了提醒自己做一個好的bug報告者，特保存文章在此。另外，爲了以後方便查閱，提取了文章內容，加入自己的一些想法。
引言
拙劣的bug（計算機程序代碼中的錯誤或程序運行時的瑕疵——譯者注）報告例子：
- 在報告中說“不好用”
- 所報告內容毫無意義
- 在報告中用戶沒有提供足夠的信息
- 在報告中提供了錯誤信息
- 所報告的問題是由於用戶的過失而產生的
- 所報告的問題是由於其他程序的錯誤而產生的
- 所報告的問題是由於網絡錯誤而產生的
“技術支持”很可怕的工作？——因爲有拙劣的bug報告需要處理。
好的bug報告的特性：非常清晰、有幫助並且“有內容”。
本書所有指導方針，非必須恪守
不同的程序員會喜歡不同形式的bug報告。以程序附帶了一套報告bug的準則爲準
如何寫一個好的bug報告
基本要求
表意清楚
如果程序員不知道您說的是什麼意思，那您就跟沒說一樣。儘量做到清晰並且有用精確
如果做相同的事情有兩種方法，請說明您用的是哪一種。例如：“我選擇了‘載入’”，可能意味着“我用鼠標點擊‘載入’”或“我按下了‘ALT+L’”，說清楚您用了哪種方法，有時候這也有關係。詳細
信息寧多毋少！如果您說了很多，程序員可以略去一部分，可是如果您說的太少，他們就不得不回過頭再去問您一些問題。慎用代詞
諸如“它”，“窗體”這些詞，當它們指代不清晰的時候不要用。來看看這句話：“我運行了FooApp，它彈出一個警告窗口，我試着關掉它，它就崩潰了。”這種表述並不清晰，用戶究竟關掉了哪個窗口？是警告窗口還是整個FooApp程序？您可以這樣說，“我運行FooApp程序時彈出一個警告窗口，我試着關閉警告窗口，FooApp崩潰了。”這樣雖然羅嗦點，但是很清晰不容易產生誤解。檢查
重新讀一遍您寫的bug報告，您覺得它是否清晰？如果您列出了一系列能導致程序出錯的操作，那麼照着做一遍，看看您是不是漏寫了一步。
注意：
報告bug的目的是爲了讓程序員看到程序的錯誤
您可以親自示範，也可以給出能導致程序出錯的、詳盡的操作步驟。如果程序出錯了，程序員會收集額外的信息直到找到錯誤的原因；如果程序沒有出錯，那麼他們會請您繼續關注這個問題，收集相關的信息。可以省去推測，但是千萬別省略事實
在bug報告裏，要設法搞清什麼是事實（例如：“我在電腦旁”和“XX出現了”）什麼是推測（例如：“我想問題可能是出在……”）。少一點激憤之詞，多一點有用的信息
當您報告bug的時候（既然您已經這麼做了），一定是希望bug得到及時修正。所以此時針對程序員的任何過激或褻瀆的言語（甚至謾罵）都是與事無補的——因爲這可能是程序員的錯誤，也有可能是您的錯誤，也許您有權對他們發火，但是如果您能多提供一些有用的信息（而不是激憤之詞）或許bug會被更快的修正。常懷感恩之心
請記住：如果是免費軟件，作者提供給我們已經是出於好心，所以要是太多的人對他們無禮，他們可能就要“收起”這份好心了。
“出了問題之後，該怎麼做”
一旦電腦出了問題，先不要動
不要按任何健。仔細地看一下屏幕，注意那些不正常的地方，記住它、寫下來、或者拍下來。
慎重地點擊“確定” 或“取消”，選擇一個最安全的。
出現問題之後，關掉受影響的程序或者重新啓動計算機都不好，一個解決問題的好辦法是讓問題再次產生。程序員們喜歡可以被重現的問題，快樂的程序員可以更快而且更有效率的修復bug
如果程序不好用
是不是Bug——查詢“已知bug列表”
許多程序，特別是自由軟件，會公佈一個“已知bug列表”。如果您找到的bug在列表裏已經有了，那就不必再報告了，但是如果您認爲自己掌握的信息比列表中的豐富，那無論如何也要與程序員聯繫。您提供的信息可能會使他們更簡單地修復bug。報告bug：提供儘可能多的信息，以供程序員重現——操作、環境
程序員不是弱智：如果程序一點都不好用，他們不可能不知道。他們不知道一定是因爲程序在他們看來工作得很正常。所以，或者是您作過一些與他們不同的操作，或者是您的環境與他們不同。他們需要信息，報告bug也是爲了提供信息。信息總是越多越好。尋求幫助時，應該說明答案出處
如果您不是報告bug，而是尋求幫助，您應該說明您曾經到哪裏找過答案，（例如：我看了第四章和第五章的第二節，但我找不到解決的辦法。）這會使程序員瞭解用戶喜歡到哪裏去找答案，從而使程序員把幫助文檔做得更容易使用。
報告bug的最好的方法之一——“演示重現”
報告bug的最好的方法之一是“演示”給程序員看。讓程序員站在電腦前，運行他們的程序，指出程序的錯誤。讓他們看着您啓動電腦、運行程序、如何進行操作以及程序對您的輸入有何反應。他們會觀察程序測試中的每一個細節，並且選出他們認爲有用的信息。
也許他們覺得還需要更多的信息，會請您重複剛纔的操作。他們可能在這期間需要與您交流一下，以便在他們需要的時候讓bug重新出現。他們可能會改變一些操作，看看這個錯誤的產生是個別問題還是相關的一類問題。如果您不走運，他們可能需要坐下來，拿出一堆開發工具，花上幾個小時來好好地研究一下。
無法直接演示的時候
如果您必須報告bug，而此時程序員又不在您身邊，那麼您就要想辦法讓bug*重現*在他們面前。當他們親眼看到錯誤時，就能夠進行處理了。
確切地告訴程序員您做了些什麼
如果是一個圖形界面程序，告訴他們您按了哪個按鈕，依照什麼順序按的。如果是一個命令行程序，精確的告訴他們您鍵入了什麼命令。您應該儘可能詳細地提供您所鍵入的命令和程序的反應。把您能想到的所有的輸入方式都告訴程序員
如果程序要讀取一個文件，您可能需要發一個文件的拷貝給他們。如果程序需要通過網絡與另一臺電腦通訊，您或許不能把那臺電腦複製過去，但至少可以說一下電腦的類型和安裝了哪些軟件（如果可以的話）。
無法重現
不是bug——彼此認知上的差異
如果您給了程序員一長串輸入和指令，他們執行以後沒有出現錯誤，那是因爲您沒有給他們足夠的信息，可能錯誤不是在每臺計算機上都出現，您的系統可能和他們的在某些地方不一樣。有時候程序的行爲可能和您預想的不一樣，這也許是誤會，但是您會認爲程序出錯了，程序員卻認爲這是對的。詳細描述Bug信息——而不是“程序出錯了”
精確的描述發生了什麼。精確的描述您看到了什麼。告訴他們爲什麼您覺得自己所看到的是錯誤的，最好再告訴他們，您認爲自己應該看到什麼。如果您看到了錯誤消息/錯誤消息號，一定要仔細、準確的告訴程序員
只報告“程序出了一個錯”是毫無意義的，除非您把錯誤消息一塊報上來。
不要以爲您看不出錯誤消息/錯誤消息號代表什麼意義，它就沒有意義。
有價值的線索——錯誤消息、錯誤消息號、coredump以及一些莫名其妙的延遲，就像辦案時的指紋一樣重要，保存好。這樣的話，程序員的排錯工作會十分高效。
錯誤消息系統所報的錯誤消息正好幫助了他們知道是什麼出問題。在這種情況下，程序員只要修正錯誤，而不用去找錯誤。
錯誤消息號包含了能被程序員讀懂的各種信息，並且很有可能包含重要的線索。給錯誤消息編號是因爲用語言描述計算機錯誤常常令人費解。用這種方式告訴您錯誤的所在是一個最好的辦法。如果您沒有更好的方法記住這些消息，就把它們寫下來。
內核輸出文件記錄了完整的程序狀態，也就是說任何祕密（可能當時程序正在處理一些私人信息或祕密數據）都可能包含在內核輸出文件裏。間歇性問題？
例如：程序每星期出一次錯，或者偶然出一次錯，或者在程序員面前從不出錯（程序員一離開就出錯。——譯者）。當然還有就是程序的截止日期到了，那肯定要出錯。
大多數“間歇性錯誤”並不是真正的“間歇”。其中的大多數錯誤與某些地方是有聯繫的。有一些錯誤可能是內存泄漏產生的，有一些可能是別的程序在不恰當的時候修改某個重要文件造成的，還有一些可能發生在每一個小時的前半個小時中（我確實遇到過這種事情）。
程序員想要確定他們正在處理的是一個真正的“間歇性錯誤”呢，還是一個在另一類特定的計算機上纔出現的錯誤。他們想知道有關您計算機的許多細節，以便了解您的機器與他們的有什麼不同。有許多細節都依仗特定的程序，但是有一件東西您一定要提供——版本號。程序的版本、操作系統的版本以及與問題有關的程序的版本。
如果程序員向您詢問額外的信息，或者希望你能進行一些操作，記住要好好合作，這樣可以快速縮小問題範圍。
即便您自己的“診斷”有時真的有幫助，也要只說“症狀”。“診斷”是可說可不說的，但是“症狀”一定要說。就像去醫院，不可能不說症狀，直接讓醫生給你治療自診斷出來的結果。
小結：
bug報告的基礎要求是表述清楚，確保您的意思不能被曲解。
bug報告的首要目的是讓程序員親眼看到錯誤。如果您不能親自做給他們看，給他們能使程序出錯的詳細的操作步驟。
如果首要目的不能達成，程序員不能看到程序出錯。這就需要bug報告的第二個目的來描述程序的什麼地方出毛病了。詳細的描述每一件事情：您看到了什麼，您想看到什麼，把錯誤消息記下來，尤其是“錯誤消息號”。
當您的計算機做了什麼您料想不到的事，不要動！在您平靜下來之前什麼都別做。不要做您認爲不安全的事。
儘量試着自己“診斷”程序出錯的原因（如果您認爲自己可以的話）。即使做出了“診斷”，您仍然應該報告“症狀”。
如果程序員需要，請準備好額外的信息。如果他們不需要，就不會問您要。他們不會故意爲難自己。您手頭上一定要有程序的版本號，它很可能是必需品。
總的來說，最重要的是要做到精確。程序員喜歡精確。
版權所有 Simon Tatham 1999
本文屬於OPL（OpenContent License），請在複製和使用本文時自覺遵守OPL。
對本文的任何意見和批評請發送至：
英文版：[email protected]
中文版：[email protected]