有沒有遇過一種情況是，即使需求不是這麼急迫，團隊之中總有習慣了問題來隨手就解的隊友，那個神來一筆的 commit 也跟著埋下了考古的鑰匙。
直到要維護時，你才發現你就是這個考古學家，戴上帽子拿起放大鏡，要來探索這看似熟悉卻陌生的語言。
「咦，這些簡寫是什麼意思？」
「這個 function 命名跟行為怎麼不一樣？」
「status == 5 是指什麼啊？」
於是你帶著各種疑問繼續在迷宮打轉，此時多希望有翻譯蒟蒻。
也許，我們都應該多在乎一點別人，在每次 commit 後，檢討一下這次提交內容的可讀性，是否能夠輕易被理解？
這篇文章主要會和大家分享，在過去的開發歷程以來，和非常厲害/困擾的高手合作後，整理出這些對我或團隊來說能夠提升「可讀性」的方法，而這些技巧方法也直到現在都還在使用。
文章的篇幅主要會分成三個部分
- 提升可讀性能夠帶來的實際幫助 <- 本篇
- 以程式碼示範提升可讀性好用的技巧
- 以測試、開源等不同角度去提升可讀性的方法
在程式碼範例的部分，主要會以 Ruby / JavaScript 的語法作為示範，其寫法盡可能會寫的繁瑣一些，其目的是希望能夠讓其他語言的學習者也能夠理解。
序
- 提升可讀性能夠帶來的幫助
- 這篇文章會寫什麼？
- 你知道國語和國文的差別嗎？
- 可讀性帶來什麼幫助
- 用實際開發案例說明提升可讀性好用的技巧
- 觀念
- 命名
- 註解
- 流程
- 以測試、開源等不同角度去提升可讀性的方法
- 性能與可讀性
- 約定優於配置
- 社群規範 Ecosystem
- 以測試角度提升你的可讀性
- 總結
這篇文章會寫什麼？
我們都知道，網路上有很多文章分享程式碼如何改善可讀性，甚至會推薦你去看 Clean code / The Art of Readable Code / Implementation Patterns，等等一些文章筆記或書籍。
懶的人也可以在網路上找到別人消化過的筆記文章。
但看完這些文字後，對於實務上還是不清楚怎麼改善，也不曉得可讀性這種抽象的標準到底在哪裡，畢竟好不好理解，是相對主觀的。
以 Kent Beck 所寫的 Implementation Patterns 一書，其內容提到了 77 個實作的 patterns，這概念又與 Clean code 所提到的不完全相同，只能說對於軟體開發的設計模式，各自有不同的見解。
但能夠讓程式碼可以在開發時具有「溝通」的效果，卻是一致的目標，所以這篇文章主要會和你分享，在程式撰寫時，可讀性的重要及如何透過一些簡單的觀念來建立並提昇自己，加強自己在撰寫能力上的內功心法。
這些方法是我自己整理出來比較常見，可以快速調整方向或思維的作法。
有趣的是，我在過去一年裡，同時寫了 Ruby / Go / React Native 的專案，在以下的範例內容，我會盡可能以簡單的變數命名、變數命名、function 來作為表達，想和你分享的是，可讀性的基本功夫是可以貫穿程式語言的。
你知道國語和國文的差別嗎？
在程式開發中，良好的可讀性必然是系統健全體質的重要指標之一，這個指標能夠如何幫助我們提升開發效率及品質呢？
有多少次，我們聽見「之後在改」，但往往事實是將這段程式碼放置到遙遙無期封塵已久，直到回首時，才發現這個撰寫的時日已經是一年前了。
其實更常發生的情況是，常常覺得不可置信，卻也不可否認的情況，就是這個程式碼你只會寫這麼「一次」，一時貪快而未曾深思的你選擇了 work/hack around 的做法，雖然能夠解決當下的問題，但也同時為未來的自己或他人埋下迷宮的關卡。
或許你會說，現在很急著要上、老闆明天就要、公司我最資深啊，以及各種不可抗拒的理由，所以你被時程逼迫寫下可讀性可能不是太好的程式。
但我們換個角度仔細想想，如果有一場 50 分鐘的演講你即將上台，但主辦方臨時將時間更改成只有 10 分鐘，那麼你說話的方式、語句會從口齒清晰變成含糊不清嗎？
通常不會。
因為你已經習慣你的說話方式，或許這個改變讓時間變的有限，內容也被侷限，但你能說出的內容取決於你的內涵及所學，並不會差太多的，因為表達方式已經內化到你的大腦裡了，也就像是武俠小說所說的內功。
為什麼我們小時候在上課的過程中，國小學習的是「國語」，而到國中之後變成「國文」
因為這是兩個完全不同的領域
- 國語: 讓你認識基本單字、字詞及基本用法
- 國文: 讓你學習文字的運用，各種句子、形容來完整表達自己的想法。
所以當你學會了程式語言中的 if else / loop / API，那就像是學習「國語」，也就是所謂基礎用法，你明白程式可以透過參數傳遞、條件判斷，來達到不同的執行結果。
而將想法轉成程式碼時，如果沒有學好「國文」，自然容易寫出不具可讀性的程式碼，再加上我們的母語並不是英文，對很多人而言，只把程式語言的英文當做積木來拼湊，而不是把他當一個句子或文章來看待。
所以當把「國文」學好時，時間久而久之會內化成你的功力，我認為就算環境在嚴苛、時間再急迫，也可能因為這些情況有實作方法上的 trade off，但這時的你應當能隨手寫出「至少」能讀的程式碼了。
舉個例子，如果你習慣命名 latestPosts，不會因為時間很趕就變成 lps，因為根本不差這幾秒鐘啊
業餘跟職業的選手差別在於，職業選手透過長久的練習及內化，能夠不透過思考直接反射性的使出高階招式。
這對選手來說，是境界的不同，對工程師來說，何嘗又不是如此呢？
可讀性帶來什麼幫助
提升效率
在寫程式碼時，總是很難在第一時間就「完全正確」，所以或多或少會有除錯的時間，難以閱讀的程式碼就像是一座迷宮，不僅迷惑了自己還會讓協作者花更多時間去理解。
或許你有高超的記憶力，能夠很快的從迷宮逃脫，但通常一段時日過後回頭來修改維護時，會重新挑戰你的記憶力，不易讀懂得程式碼將會再度浪費你的開發時間。
所以，可讀性提升的是未來自己和他人的開發效率。
減少犯錯
良好的可讀性也就意味著表達明確，而不是曖昧不清或隱諱的敘述。
當一段程式碼的命名敘述不同於執行內容時。
在現實生活中你會說這產品廣告不實、在機場海關這叫偷渡、在女生嘴裡叫口是心非，但在開發程式時卻叫他媽的誰放的地雷。
我們來看以下的例子
def increase_read_count(post)
post.update(read_count: post.read_count + 1)
SendEmail.perform(post)
return post
end
我們以為 increase 會如同字面上的意思只是單純增加計數，但如果沒仔細去看實作細節，他竟然還會偷發一個不知道做什麼用的 Email，這就屬於一種隱諱的寫法，因為和主要敘述功能的名稱不完全符合，也難以聯想。
所以，明確的表達能夠減少犯錯。
幫助他人學習
可讀性高的程式碼，能夠讓人更快進入狀況，瞭解其邏輯、設計架構，而減少時間在搞懂這迷宮到底怎麼蓋的，能夠展現其思緒及脈絡。
不論對於他人學習或團隊合作都有很好的幫助，以 clean code 的名言來說，也就是
當每個你看到的程式，執行結果都與你想得差不多，你會察覺到你正工作在 Clean Code 上
所以，可讀性能夠幫助他人和自己更快學習。
小結
在接下來的章節，會以程式碼的實際案例來和你分享如何透過思路上的調整，去提升可讀性。
請繼續閱讀下一篇章。
本系列其他文章