iT邦幫忙

2018 iT 邦幫忙鐵人賽
DAY 3
0
Software Development

淺談軟體開發與工程的基本追求系列 第 3

Issue Description (2)

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

作法

標題(Issue title)

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

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

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

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

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

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

版本(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 字左右為一個斷點,雖然可能就無法把第一天提到的項目都在這三十天講完,但也希望透過這樣維持著文章的品質,並且拋磚引玉的帶動讀者們的思考與討論囉。我們明天見。 = )


上一篇
Issue Description (1)
下一篇
Issue Description (3)
系列文
淺談軟體開發與工程的基本追求5

尚未有邦友留言

立即登入留言