6

如何提升你的程式可讀性之實務技巧（三）

 2 years ago
source link: https://blog.niclin.tw/2020/02/29/readable-code-3/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
neoserver,ios ssh client

本系列其他文章

文章的篇幅主要會分成三個部分

  1. 提升可讀性能夠帶來的實際幫助
  2. 以程式碼示範提升可讀性好用的技巧
  3. 以測試、開源等不同角度去提升可讀性的方法 <- 本篇

性能與可讀性

在這裡我會建議，可讀性優於技巧的展現，有些工程師會為了展現對程式語言的嫻熟度，在程式中使用比較冷門的語法或技巧，這通常很容易會降低程式碼的可讀性，也容易讓其他人犯錯。

而許多比較高效能的撰寫方式，通常會以可讀性做為代價，除非你很確定這段程式碼就是效能瓶頸，否則不建議太早最佳化，在第一時間應該選擇可讀性較高的寫法，而非高效能的寫法。

程式碼是寫給人看的不是給電腦看的，只有在編譯過後的 0 和 1 才是真正給電腦看的，所以在與他人協作的情況下，程式可讀性應該為第一重要。

約定優於配置（convention over configuration）

提升可讀性的方式有很多種，每個團隊因應成員的組成也有不同的習慣，不見得有一套萬全的方法能夠適用每個團隊。

但大方向不變，就是要讓協作的隊友能夠有一套方式互相看的懂對方的產出，來達到最大的開發效率。

試想，如果有一個團隊有各種大神，每個寫法不一，互相拉扯，那麼開發效率不會因為高手齊聚一堂而變快。

相反得，如果有一套 convention 明確，大家的產出都照著走，就算有人中途離開了，也不會很難接手他的東西。

但建立 convention 的過程需要不斷嘗試調整，在初期可以先多參考其他人的做法，慢慢先從放寬在開始緊縮調整規則。

社群規範 Ecosystem

在寫過比較多程式語言後，你會發現基本功幾乎都能通用，大概會是 API 的熟悉程度差別而已。

不過每個社群有不同的風氣和規範，可以多參考社群有沒有一套已經有的 convention。

以 golang 來說，會比較希望在視野可見且參數生命週期短的地方寫簡寫

而以 Rails / React 來說，通常會希望比較完整的命名去描述，在參數循環時也比較少使用簡寫

你可以試著思考，簡寫真的不好嗎？

  • 那為什麼 Golang 的社群規範會有明確的規範如何撰寫簡寫？
  • 那為什麼 React 不將 componentDidMount 改成 cDM

所以這部分要端看你所學的程式語言或框架，目前在社群上什麼樣的寫法是比較常見的，盡可能的去遵循。

因為通常大家都是和你一樣上網學同一套框架，如果你不研究社群規範，而自立門戶，往往遇到的情況就是

  1. 你公司招的新人，看不懂你的規範為什麼和外面不同，就要花更多時間磨合
  2. 你從公司離開了，到下一間公司，要重新習慣寫法

以測試角度提升你的可讀性

在一定的組織規模，或是有一定自我要求及時間足夠的工程師上，通常都會面臨到寫測試。

測試通常有粒度的不同，由小而大，從單元測試到整合測試，也可能會有職責的不同，從工程師負責的 unit test 到 QA 負責的更多整合測試、黑白盒測試等等

撰寫測試的好處是什麼？

  1. 替你省掉手動測試的時間
  2. 替你省掉回歸測試的時間
  3. （重點）提升你的程式碼設計品質

為什麼寫測試能夠提升程式碼設計的品質？

# 你看的懂這個測試為什麼狀態會從 1 到 2 嗎？
expect { service.perform }.to change { order.status }.from(1).to(2)

# 這樣是不是清楚多了
expect { service.perform }.to change { order.status }.from("done").to("failed")

因為從寫測試的角度回頭去看自己的程式碼時，你會發現，測試怎麼這麼難寫，有各種耦合，想 mock 某個 function 結果整陀都被 mock，導致結果不如預期，無法測到所想的預期。

為了要測一個單元，結果必須要製作各種資料才能完成，那就間接的代表，這個 function 耦合了什麼。

所以你在設計程式的時候，也可以同時以測試的角度下去看，我這個 function 容易被測試嗎？

當你的 function 開始趨近於單純，也就呼應文章上面寫到的單一職責，你會在設計的過程中避免這個 function 負責太多事情。

到這裡你就會理解，負責太多事情只會

  1. 難以抓 bug
  • 易於被測試的 function，通常也是職責單純的 function。
  • 能夠在測試的部分容易被閱讀，通常程式的部分都不會太糟糕。

這可能也是為什麼在 Functional Programming 推出將近五十年後，再度流行起來 XD

OpenSource

無論是創建自己的開源專案亦或是參與他人的，通常開源意味著與陌生人協作。

如果你的 code 可讀性很差，邏輯不清晰，也容易將協作者拒之門外。

因為這些協作者不像同事一樣，可以直接的到你旁邊問你這行 code 到底是什麼意思？

你需要更直觀的寫法、更詳細的註解來達到更高效的合作，除非你只想一個人維護。

通常開發到後期，可能會發現手邊那個正在使用的工具或框架有一些不足或是可以修正的地方，這時候你去該專案發 PR 時，應該都會獲得建議，或是被要求要寫測試，我認為這是一個很好的學習機會，透過與陌生人合作讓軟體開發更好，也可以借此機會從中學習。

可以嘗試閱讀一些大型開源專案，都有詳細的註解、commit、容易明白的 naming，透過這樣的機會來反思自己寫程式時的可讀性，是否易於和他人合作。

本系列文章專注於「可讀性」的提升想法及技巧，當然程式設計不會只有這一個部分需要被注意，只是在這個高速協作的時代，要不斷思考怎麼樣讓整個團隊提升開發效率其實比提升個人來的更難。

所以希望能透過一些範例、方法，來整理出一些能夠簡單提升可讀性的技巧，讓整個過程就像在上一個程式語言的文法課這樣。

經過一段開發時期後，對我而言，卓越的工程師，並不是寫程式能夠寫多快。

而是能夠撰寫出別人可以輕易看的懂與維護的程式碼，可不斷重複被使用，易於修改。

而且不是僅僅只做出當下這個功能與解決眼前的問題。

我自己也會持續在提升程式碼可讀性的道路上不斷繼續努力，關於內容有不足或謬誤的地方，也歡迎批評指教，我會儘速修正。


report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK