本日承襲自昨日的文章，所以直接從「作法」的章節繼續講述。

作法

標題（Issue title）

無論是什麼類型的文章，有個好的標題就是一個好的開始，議題的標題更是如此。如何用最少的字把異常的輪廓描述出來，就是這個資訊需要探討的。

在探討什麼是好的標題前，我們先說說什麼叫做不好的標題。讓人最討厭的標題莫過於內容農場式的標題，也就是講得很誇大，但卻什麼重點都沒提到，像是「這裡有一個很嚴重的問題造成程式崩潰了！」或是「緊急！這個異常讓客戶抓狂了！」等等。

那到底標題要如何說清楚呢？把握一個原則就是至少詳細到不容易和其他類似異常搞混，以現實生活的情境來舉例，假設今天台中某處有個路燈壞了，你想舉報請市府趕緊請人維修：

• 南區有個路燈壞了（Ｘ，太籠統，這樣同名不同處的異常可能會太多）
• 南區台中路上靠近二二八公園處有路燈壞了（Ｏ，把異常發生的地點指名）
• 南區台中路上靠近二二八公園處有路燈不斷閃爍（Ｏ，把故障狀況請得更清楚）
• 南區編號 641549 的路燈不會亮（Ｏ，善用產品本身提供的除錯輔助資訊）

另外多用客觀的描述取代主觀看法也會讓標題更好識別：

• 網站的選單很難用，一直沒反應（Ｘ）
• 網站的選單按鈕太小了，觸控容易失敗，或是誤觸其他按鈕（Ｏ）
• 網頁會跳出奇怪的畫面，不知道發生什麼事（Ｘ）
• 點擊編輯文章的按鈕，會跳出「We're sorry, but something rent wrong」的畫面（Ｏ）

版本（Version number）

產品發生異常時的版本號非常重要，它可以開發者確認這個異常是在產品開發的什麼時間點發生的，是否已經在比較新的版本被修復了？或是該行為在以前沒問題，直到某個版本後才發生異常，開發者能透過版本號鎖定變動的位置，了解前後的脈絡，判斷是不是有一個變動提交（commit）沒有注意細節而引發了異常。

若說標題和描述是讓開發者了解空間與事件，那麼版本就是讓開發者知曉時間。在兩者資訊充足的情況下，雙方對談就容易聚焦，而不是在跟平行世界的對方雞同鴨講。

所以程式在釋出時應該要有一套版本號訂定風格，讓使用者在回報異常時，開發者能迅速聚焦在準確的範圍去除錯。若是程式是沒有明確版本號，提供程式當前版本控制紀錄中的資訊（通常是最後一次提交的雜湊值）也是個方式。

問題描述（Describe the problem）

如果好的標題是一個好的開始，那麼問題簡述就是把這個好的開始延續下去。標題通常必須一句話簡述整個異常的輪廓，那問題描述就是把異常的細節描繪出來。標題中省略的細節、脈絡，或是你對這個問題的觀察和看法，都可以在這裡好好詳述。若同樣以路燈為例，那大概就是：

南區台中路上靠近二二八公園處有路燈壞了，它時不時在閃爍。這附近只有這個路燈有異常現象，其他路燈都是好的，該路燈的編號是 641549 。看它的桿身似乎有被撞擊過的痕跡，或許是最近被車輛擦撞過導致線路異常？我沒有很確定。詢問過附近的居民，似乎在前天還是好的。

在這個例子，可以看到除了標題所提到的資訊外，還多了許多來自於回報者的觀察，讓我們可以有更多資訊的得以除錯。

• 異常描述：閃爍
• 同型比較：和其他路燈相比
• 產品資訊：路燈編號
• 額外表徵：被撞擊過的痕跡
• 個人推斷：或許是被擦撞過導致線路異常
• 其他資訊：詢問居民

用路燈來描述可能還是有點籠統，很難和實際程式做聯想結合，這邊改以登入發生錯誤的情境作為舉例：

用帳號密碼登入後，會跳到顯示 We're sorry, but something rent wrong 的畫面

輸入帳號密碼登入後沒有跳到正常頁面，而是顯示錯誤訊息的頁面（異常描述），出現錯誤訊息的網址是 https://xxx.xxx.xxx/ooo?a=aaa&b=bbb（產品資訊）。其他頁面似乎都正常，透過社交平台登入的功能也正常（同型比較）。不管輸入的帳號密碼是否正確都會報錯。我不知道發生什麼事，會不會是帳號密碼驗證的程序出錯？因為社交平台登入是正常的（個人推斷）。問過朋友，他們使用帳號密碼登入也有同樣的異常。有朋友說早上七點時還是正常的（其他資訊）。

當然，這些特徵與資訊項目都只是舉例，每個專案或情境可以提供的資訊類型都不相同，但希望這樣舉例能讓讀者們稍微了解「問題描述」與「標題」的差異，以及有什麼細節是可以提供的。

重現步驟（Steps to reproduce）

重現步驟就是指經過哪些動作後，就一定會引發這個異常。這是讓開發者代入異常發生情境很重要的資訊。如果沒有提供重現步驟，開發者就要耗費更多時間去分析到底發生了什麼事，然後嘗試要如何重現，能將異常重現後才能開始進行除錯。如果直接提供重現步驟，那開發者就能直接面對異常，然後依照他的經驗快速除錯。

有重現步驟的異常回報，也容易使回報者和開發團隊站在同一個視角，而不是使用者一直在幹譙，然後開發團隊只能不斷道歉，卻還是找不到異常發生的原因，或是直接丟給使用者「這在我電腦是正常的！（It works on my computer!）」交差了事。當開發團隊非常努力想透過回報者的描述去重現異常，卻一直失敗時，面對回報者的催促，有可能會產生負面情緒，認為回報者是來鬧的，畢竟在兩者的觀點上，對方描述的事情都是沒發生過的呀！

若是該異常無法百分之百重現，也要在這裡特別講明。儘管沒有一個肯定能重現的步驟，但仍可以試著把可能會發生異常的步驟寫出來，讓開發者了解到底再發生這個異常前，會經歷過什麼事，導致有機率觸發異常。回報者也需要有著「在沒有有永遠能重現異常的步驟時，這個議題可能會需要耗費較長時間除錯」的心理準備。

好的重現步驟在於一個指令一個步驟，先以上節提到的登入異常為例，大致如下：

1. 進入網站（https://www.xxxx.tw）
2. 點擊首頁右上方的「登入」按鈕
3. 再登入表單中輸入帳號密碼
4. 點擊表單中的「送出」按鈕
5. 發生異常

雖然這個例子這個重現步驟看起來似乎沒提供到什麼資訊，但某種層面上卻也讓開發者知道使用者是用合理的方式去進行登入，可以排除是非預期的行為模式導致異常發生。透過這樣一個指令就寫一個步驟的，讓開發者了解實際的行為模式，也讓開發者依照這樣的步驟執行時，能夠代入使用者的情境。若是開發者在執行步驟時是正常的，就可能會往是不是環境或版本的不同造成結果差異的方向去想，而不是不斷在程式碼中鑽牛角尖。

若回報者在使用產品時，有了一些非預期行為是開發者當初沒有想到的，就可以讓開發者不被既有的觀點束縛，突破盲點而瞭解錯誤的原因。畢竟我們都知道，身為開發者去執行一些情境，都一定會預設我們心中已經非常熟悉的合法步驟，而不會意識到有其他非預期行為的可能。

另外，若是能夠在每個步驟都附上畫面截圖，也會減少對步驟執行的誤解，並透過畫面提供了回報者可能沒意識到的額外資訊。

TO BE CONTINUED

---

本日感想（無關主題）
昨天想要一次把這個主題講完果然是狂妄到想法 XD。原以為能夠很簡單的把這個主題帶過，但邊寫就會迸出更多想法以及更好的表達方式，例如輔以更多舉例之類的。

之後的發文我都會以 2500 字左右為一個斷點，雖然可能就無法把第一天提到的項目都在這三十天講完，但也希望透過這樣維持著文章的品質，並且拋磚引玉的帶動讀者們的思考與討論囉。我們明天見。 = )