When life gives you lemons, write better error messages

似乎很少看到有文章認真地探討，該如何適當地撰寫軟體系統中的錯誤訊息。來自 Wix UX 團隊的文章《When life gives you lemons, write better error messages》，描述了 Wix 網站平台如何對錯誤訊息的表達做出檢討，擬定新的原則，並投注心力加以改善。

這是一篇很值得一讀的文章，雖然當中的概念，主要是針對一般用戶，可能不一定都適用在不同的情境中。比方說在微軟產品裡，經常是僅僅丟出一長串的錯誤代碼，讓使用者自己按代碼去搜尋解答。儘管這確實應該是有改善空間，不過採用錯誤代碼的方式，背後應該也是有其工程考量。而非蓄意的怠惰，然後把麻煩轉嫁在使用者身上。

在 DR 的觀念裡，倘若不知道錯誤訊息該怎麼寫，那麼最至少就是單純地把事實陳述出來。說明發生了什麼事，以及根據程式的設計邏輯，盡可能準確表達出問題的來源。

回想起來，DR 有一個印象頗為深刻的經驗，反而不是因為錯誤訊息語焉不詳或什麼的，而是軟體發生錯誤卻完全沒有錯誤訊息，進而造成的問題。話說以前在主機商做值班工程師時，公司有運用開源軟體弄了一個反映 Nagios 監控狀態的電子告示板。那麼以日常的值班任務來說，自然就是會依賴告示板上所顯示的訊息，工程師經常得盯著告示板看有無狀況發生。

應該是在某次處理 MySQL 的維護事項時，赫然發現明明服務是關閉狀態，告示板卻沒有出現相關告警，反而顯示系統一切正常。考量到工程師對於告示板訊息的依賴，告示板上沒有反映出真實狀態可是件很嚴重的事情，所以就很快地跟主管回報。然而由於告示板是一個在起初建置完畢後，就沒有什麼人去碰的東西，所以大家都不是很瞭解，因此又花了點時間重新弄清楚它的運作細節。

後來在告示板的 PHP 程式碼裡排查出問題的肇因，是來自於發送給告示板的 JSON 內容，因某些狀況而帶有無法被 UTF-8 解碼的字元，進而造成 json_decode() 失敗。而告示板的程式邏輯並未去應對這樣的錯誤風險，直接把讀不出 JSON 當作是沒有狀況，便出現了失真的結果。於是幾經評估，認為比較穩妥的解決方案，是修改程式碼，在執行 json_decode() 之前先用 mb_convert_encoding() 處理掉無法解碼的字元，以確保 JSON 讀取的可靠性。