[心得] 「命名」這個問題的本質

[AmosYang (泛用人型編碼器)]

《程式英文》 https://github.com/EngTW/English-for-Programmers 上週跨過了
「GitHub 500 星」的里程碑，在此整理一下這 12 週以來的心得。

* 討論了 64 個與程式寫作有關的英文字
* 每週新主題的熱門程度不一，點閱人次分佈在 3000 ~ 5000
* 每週流量有大約 10% 是重訪既有主題

---
* Google 文件 https://bit.ly/2GvWwV2
* GitHub 討論區 https://bit.ly/321ResR

---
# 「命名」這個問題的本質

寫程式時，「好的命名」的作用可說是：

* 以精練的文字引導程式碼讀者的大腦聚焦在最重要的相關知識與經驗上
  * 進而掌握程式碼的 How & Why

「好的命名」很重要，但「命名得好」很難，我將「命名的難處」歸納如下：

* 缺乏學習誘因
  * 就「寫程式的當下」來說，最低限度的要求／短期報酬最高的目標，可說是「
    寫出能用的程式」。
  * 而「可讀性／好的命名」的短期報酬相對地低。
* 缺乏練習環境
  * 就「語法、邏輯」來說，取得意見回饋很容易；可以用程式語言工具檢查語法
    ，可以演算驗證邏輯。
  * 而「可讀性／命名」的品質評鑑是相對地困難。
* 缺乏技術指導
  * 在這個時代可以找到許多「命名常規(convention)」的資料，是很有用的「語
    法(syntax)、格式(format)」參考資料；同時，也有相當的資料在探討「命名
    的原則」及討論「命名案例」。
  * 而「命名的語意(semantics)」的資料相對地少。

---
那麼，要如何克服上述的難處？我的看法如下：

## 學習誘因

誘因(incentive)、動機(motivation)是個很大的題目，這裡先談個人容易著手的
方向：「管理工作記憶區、調節情緒」，也就是降低「問題的複雜度、覺得困難的
情緒」對動機的負面影響。

易言之，如果目前無法做到「一次寫出能用又好讀的程式」，試試分成「寫出能用
的程式」、「寫出好讀的程式」兩個步驟來做。

可以參考 Test-Driven Development (TDD) 工程方法的原則，先寫出「能用、好
掌握、好測試的程式」，再來改善程式的可讀性（後面會探討實作方法）。

另一方面，「團隊文化、報酬制度」是個人相對難著力的方向，因為那通常不是技
術問題，而是商業問題。

## 練習環境

這個時代有不少「語法檢查工具」，但幾乎沒有「語意檢查工具」；目前我能想到
的替代品有三：

* Pair Programming
* Code Review
* 社群討論
  * 例如這一系列文章
  * 或我開設的 https://github.com/EngTW/English-for-Programmers/issues

或許，將來有一天，《程式英文》累積了足夠了「命名」知識與經驗，可以試著開
發出某種「命名語意檢查工具」，但目前還是得依賴人腦。

## 技術指導

這個時代有很多很棒的書與參考資料，但我發現既有的參考資料在「命名的語意」
這方面相對的薄弱。而對母語非英語的我們來說還有「英文語意」這個門檻。

經過過去 12 週的嘗試，我發現從語源學(etymology)的角度可以有效地釐清英文
字的語意；《程式英文》會繼續探討「程式命名常用字」的語意、字面上的意思
denotation vs. 使用情景中的意思 connotation 、語法、格式。

另一方面，我從學術論文著手，看看學界是怎麼研究「程式命名」這個題目；以下
是我最近讀的資料的歸納整理：

### 「命名」的方法

0. 當你想要命名一個東西時
1. 你想要傳達的概念有哪些？例如：
   * 需求，這東西的目的為何？它被用來解決什麼問題？
   * 情境，這東西的上下文為何？
   * 地雷，這東西有什麼違反直覺、違反業界常規的地方？
   * 參考 https://www.ptt.cc/bbs/Soft_Job/M.1546163575.A.4C5.html ，還有
     哪些概念會讓你覺得需要為它寫註解？
2. 把這些概念記錄下來
   * 不要在意文法、不要在意用字、不要在意篇幅長短
   * 先粗略地大量蒐集資料，之後再來精練品質
3. 避開「知識的詛咒」，例如：
   * 暫時離開這個工作環境，讓你的大腦忘掉這一切
   * 或著，找人跟你 pair programming, code review, 討論
4. 把那些概念依重要性排序
   * 就團隊文化、業界常規來說，有哪些概念是獨特到要特別說出來的？
5. 就最重要的概念來說，有哪些字可以代表該概念？
6. 用那些字來組合出那東西的名字
7. 找人 code review, 評估你想出來的名字的品質，是否能做到：
   * 以精練的文字引導程式碼讀者的大腦聚焦在最重要的相關知識與經驗上
     * 進而掌握程式碼的 How & Why

參考資料：

* Feitelson, D., Mizrahi, A., Noy, N., Shabat, A. B., Eliyahu, O., &
  Sheffer, R. (2020). How Developers Choose Names. IEEE Transactions on
  Software Engineering.

### 「鑑定命名品質」的方法

* 命名要適合放在工作記憶區的大小
  * 一般人腦大約能同時掌握 3 ~ 4 個概念與那些概念之間的關係
  * 一般人腦的「一看就懂」是指在約 2 秒內能看懂一個概念
  * 母語為英語者，一般閱讀速度是約 1 秒 4 個英文字
* 命名要精練(concise)，例如：
  * 假設我們想要命名「輸出檔案的名稱」變數
  * `output_file_name` 是個好名字，它 正確 且 精練
  * `file_name` 會是個 正確 但 不精練 (不嚴謹) 的名字
  * `foo` 是 不正確 也 不精練
* 命名要一致(consistent)
  * 假設某程式中， `file` 在某個地方代表「檔案名稱」，
    * 在另一個地方代表「檔案指標(pointer)」，
    * 這是不一致的
    * 這裡的問題是「同一個名稱 對應到 多個概念」
  * 假設某程式中， `file` 在某個地方代表「檔案名稱」，
    * 在另一個地方， `file_name` 也代表「檔案名稱」，
    * 這也是不一致的
    * 這裡的問題是「多個名稱 對應到 同一個概念」

參考資料：

* Deissenboeck, F., & Pizka, M. (2006). Concise and consistent naming.
  Software Quality Journal, 14(3), 261-282.

---
我還在慢慢消化這些學術論文；如果對我的閱讀筆記有興趣的話，可以看看這些：

* https://www.facebook.com/twy30/posts/2641704649413183
* https://www.facebook.com/twy30/posts/2641828296067485
* https://www.facebook.com/twy30/posts/2630596570523991
* https://www.facebook.com/twy30/posts/2592785380971777
* https://www.facebook.com/twy30/posts/2630521400531508
* https://www.facebook.com/twy30/posts/2630473677202947

除了「命名的語意」外，現有的「命名常規」資料似乎也很少提到「型別(type)」
對「程式可讀性」的影響；這也是個很有趣的研究方向。

---
# 結語

「命名」這個題目很有趣，像是在打造一把鑰匙，可以打開讀者的大腦倉庫，提取
出一整個世界。

有任何關於軟體工程、程式設計的英文相關問題都很歡迎提出來討論；很多很有趣
的研究方向、靈感其實都是來自於讀者提問、意見回饋。

在此感謝所有參與討論的網友 :)

--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 136.56.13.184 (美國)
※ 文章網址: https://www.ptt.cc/bbs/Soft_Job/M.1601675826.A.A6D.html
推 adks3489: 推，命名依照用途而非內容物，就能提昇精鍊度
推 Downager: 推，這些討論很受用
推 alihue: 推推
推 Ouranos: 推推，謝謝分享~
推 summerleaves: 優文 有看有推
謝謝各位的欣賞 :)
※ 編輯: AmosYang (136.56.13.184 美國), 10/05/2020 02:04:53
推 love99067333: 想問_和-的差異
如果你是指 var_name 與 var-name 這兩種寫作風格的差異，

* 我目前尚未看到任何認知科學研究主張哪種比較好、怎麼個好法。
* 我目前看到的多是「在這個文化生態圈中，就是習慣這樣寫」。

---
很像是「小數點」的情形；例如

* 10,000.00 ← 台、美、日等國家習慣用 "." 來當小數點
* 10.000,00 ← 歐洲、一些非州國家則是用 "," 來當小數點

沒有資料說哪種比較「好」，就是文化習慣。

參考資料： https://en.wikipedia.org/wiki/Decimal_separator
※ 編輯: AmosYang (136.56.13.184 美國), 10/05/2020 04:29:36
推 guest0710: 感謝你
推 v9290026: 推推
推 BlazarArc: 推
謝謝各位的欣賞 :)
※ 編輯: AmosYang (136.56.13.184 美國), 11/08/2020 12:56:41