PTT推薦

[心得][英文] 如何命名「狀態」變數

看板Soft_Job標題[心得][英文] 如何命名「狀態」變數作者
AmosYang
(泛用人型編碼器)
時間推噓27 推:28 噓:1 →:4

本週主週:

* 如何命名「狀態」變數?
* State, Status 有什麼不一樣?
* 「第N個」要怎麼說?

* Google 簡報 https://bit.ly/2GtLobb
* GitHub 討論 https://bit.ly/321ResR

---
# State

## 語源、語意

* 1200 年代
* 人 / 物的暫時屬性、狀態
* 狀況、情況
* 社會地位
* 13 世紀後期:形、結構的物理形態
* 1530 年代:情緒、心理狀態
* 今日:人 / 物在特定時間點的狀態

## 案例

* finite-state machine 有限狀態機
* state of matter 物質狀態(固態、液態、氣態)
* 電腦科學:資訊系統、程式的狀態;記憶事件歷程的功能
* stateful 有狀態的
* stateless 無狀態的
* .NET Threading `ThreadState`
* Running, Stopped, Suspended
* .NET Data `ConnectionState`
* Closed, Open, Connecting, Executing

## 參考資料

* https://www.etymonline.com/word/state
* https://www.lexico.com/definition/state
* https://www.merriam-webster.com/dictionary/state
* https://en.wikipedia.org/wiki/State_(computer_science)
* https://en.wikipedia.org/wiki/Finite-state_machine
* https://en.wikipedia.org/wiki/State_of_matter
*
https://docs.microsoft.com/en-us/dotnet/api/system.threading.threadstate?view=netcore-3.1
*
https://docs.microsoft.com/en-us/dotnet/api/system.data.connectionstate?view=netcore-3.1

---
# Status

## 語源、語意

* 1670 年代:情況、狀況的高峰
* 1791 :人的法律地位
* 1920 :人的職業、社會地位
* 今日:情景、整體脈絡的狀態

## 案例

* exit status 退出狀態
* status bar 狀態列
* .NET Net `HttpStatusCode`
* OK, NotFound, InternalServerError
* .NET Threading `TaskStatus`
* Created, Running, Canceled

## 參考資料

* https://www.etymonline.com/word/status
* https://www.lexico.com/definition/status
* https://www.merriam-webster.com/dictionary/status
* https://en.wikipedia.org/wiki/Exit_status
* https://en.wikipedia.org/wiki/Status_bar
*
https://docs.microsoft.com/en-us/dotnet/api/system.net.httpstatuscode?view=netcore-3.1
*
https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus?view=netcore-3.1

---
# State, Status 有什麼不一樣?

state, status 都能讓讀者聯想到「狀態」這個觀念,就看你想強調哪一個面向。

* 語源都可追溯至拉丁文的 status :「狀態、形態、樣子、位置」

* state 傾向「個體『狀態』屬性」
* finite-state machine 有限狀態機
* state of matter 物質形態(固態、液態、氣態)
* .NET ConnectionState, WebSocketState, ThreadState

* status 傾向「就整體脈絡的綜合判斷;事態、情況的『狀態』」
* exit status 退出狀態
* status bar 狀態列
* .NET FtpStatusCode, HttpStatusCode, TaskStatus

例如說,在某個邏輯模型裡,可能是這樣子界定 state, status :

* 某個運算單元
* state: { 讀資料, 寫資料, 解碼, 執行指令, 閒置 } ← 此個體當前的狀態
* status: { 忙碌, 閒置 } ← 就整體脈絡的綜合判斷

也就是看寫程式的人想要如何定義「個體狀態 vs. 整體脈絡」。

## 參考資料

*
https://docs.microsoft.com/en-us/dotnet/api/system.data.connectionstate?view=netcore-3.1
*
https://docs.microsoft.com/en-us/dotnet/api/system.net.websockets.websocketstate?view=netcore-3.1
*
https://docs.microsoft.com/en-us/dotnet/api/system.threading.threadstate?view=netcore-3.1

*
https://docs.microsoft.com/en-us/dotnet/api/system.net.ftpstatuscode?view=netcore-3.1
*
https://docs.microsoft.com/en-us/dotnet/api/system.net.httpstatuscode?view=netcore-3.1
*
https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus?view=netcore-3.1

---
# 「第N個」 / 序數 / 個體在群體中的位置、索引

題目出處: https://github.com/EngTW/English-for-Programmers/issues/53

> 你好,我最近在處理股票資料的api,
> 有一個內容是我想要將資料整理成K線的形式,
> 我的Kbar calss中想要存「屬於今天中的第N根Kbar」,這種狀況要怎麼命名呢。
> 像是以一根10:00~ 10:15的15分鐘k線,8:45開盤,這個變數會存5,代表是今天
> 的第六根K線

要表示個體在群體中的「第N個」,可以用 "ordinal" 這個字,它是
「序數 (ordinal number)」的縮寫。

例如 .NET DataColumn 的 `Ordinal` 屬性,代表一 DataColumn 物件在其所屬的
DataColumnCollection 中的位置(第N個)。

要表示「個體在群體中的位置、索引」,也可以參考以下這些字,選擇最符合你想
表達的語意:

* index 索引
* id
* key
* name 名字
* title 標題

## 參考資料

*
https://docs.microsoft.com/en-us/dotnet/api/system.data.datacolumn.ordinal?view=netcore-3.1

感謝參與 https://github.com/EngTW/English-for-Programmers/issues/53 討論
的網友。

---
# 結語

適當的命名可以幫助你的讀者了解你的程式碼的意圖,降低溝通成本,減少誤會的
機率。

這系列文章將繼續從語源資料、實用性的角度,探討《程式英文》字彙的語意、使
用情景,幫助大家提昇程式碼的可讀性。

歡迎推文留言討論、提問 :)

--

※ PTT留言評論
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 136.56.13.184 (美國)
PTT 網址

jasonwung09/04 12:18

sniper282409/04 12:21推個

ihave3cm09/04 12:47推起來

deathlightx09/04 13:14此系列,必推

summerleaves09/04 13:25有看有推

newhandfun09/04 13:25

qaz010109/04 14:42受益良多,必推

ian9091109/04 15:19

BlazarArc09/04 16:28

謝謝 :)

unmolk09/04 17:12推!想看property attribution之類的要怎麼用

目前有一個題目是關於「屬性: attribute vs. property 」,我想知道這與你想 知道的 property, attribution 是同個方向嗎?如果不是,能否描述一下你的疑 問? :)

https://github.com/EngTW/English-for-Programmers/issues/25

B098869808809/04 17:41小建議:結論可以放前面嗎?上面那些單字個別解說放

B098869808809/04 17:41後面有興趣的自己會去延伸閱讀

了解,結論放前面對讀者來說比較省時省力。

uopsdod09/04 18:24

lairx09/04 18:47

CaptPlanet09/04 19:33不錯勃 有點東西

jack4210709/04 20:23推這系列 感謝用心

Ouranos09/04 21:11推推! 謝謝分享 :)

ddoy709/04 21:19

謝謝各位的欣賞 :)

※ 編輯: AmosYang (136.56.13.184 美國), 09/04/2020 23:34:14

obamina4809/04 23:39推!受益良多!

l823qqqqqqqq09/04 23:47感謝分享,有獲得啟發

謝謝 :)

unmolk09/05 00:09喔對我打錯了 是attribute XD 感謝分享!

了解 :)

CoNsTaR09/05 04:46context, env: 環境狀態

CoNsTaR09/05 04:46也可以講一下 has, with, is, at... 也可以命名狀態變數

謝謝你提供題目 :) 我把它整理成以下項目,能否請你看看與你想的方向是否一致 ?謝謝 :) * 環境狀態: context, environment 有什麼不一樣? *

https://github.com/EngTW/English-for-Programmers/issues/56

* 介詞: with, at, from, to, in, than, ... 使用情景 *

https://github.com/EngTW/English-for-Programmers/issues/57

* 現在簡單式(simple present)的使用情景 *

https://github.com/EngTW/English-for-Programmers/issues/58

* 更多「狀態」變數的實例 *

https://github.com/EngTW/English-for-Programmers/issues/59

※ 編輯: AmosYang (136.56.13.184 美國), 09/05/2020 08:53:36

ingramchen09/05 11:48通通用status,state 留給 framework 用

很有趣的想法,折衷/經驗法則。

※ 編輯: AmosYang (136.56.13.184 美國), 09/06/2020 01:53:41

changyuheng09/06 02:50

謝謝 :)

※ 編輯: AmosYang (136.56.13.184 美國), 09/06/2020 08:00:30

alihue09/06 12:46

謝謝 :)

geminitw09/06 23:27程設英文

謝謝你的建議 :) 我對這個也很好奇,就台灣的語文習慣而言,《English for Programmers》怎麼 翻會比較好? * 直譯「程式設計師英文」 * 目前稱作「程式英文」 * 鄉民 geminitw 推文提案「程設英文」 * 縮寫提案「程英」 XD 我當初是以 Google, books.com.tw 的搜尋結果為基準,「程式」似乎是最常用的 詞,就先用《程式英文》這個名字;我想知道就鄉民的中文語感來說,覺得如何。 :)

※ 編輯: AmosYang (136.56.13.184 美國), 09/07/2020 01:37:07

geminitw09/07 20:10Ex:商用英文 程設英文除了變數及函數命名 註解及技術文

geminitw09/07 20:10件才是重點

我再查了一下,從 Google 得到的數據是 * "程式書": 10900 * "程設書": 64 * "程式課": 33400 * "程設課": 5700 * "程式課程": 107000 * "程設課程": 1400 * "程式訓練": 15000 * "程設訓練": 284 似乎在「描述 "programming" 這個概念上」,「程式」比「程設」更為通用? ---

> 除了變數及函數命名 註解及技術文件才是重點

十分同意;我還沒機會去研究這個,但有個東西叫 "controlled natural language", 可說是「簡化了的自然語言」 (*1) ;可用在「針對特定技術領域,方便母語非英 文者溝通」上。 或許適合用來寫註解、技術文件。 --- *1: 限定使用相對簡單的文法與字彙,例如: * 把句子寫短 * 避免使用代名詞 * 使用主動語氣 ## 參考資料 *

https://en.wikipedia.org/wiki/Controlled_natural_language

*

https://en.wikipedia.org/wiki/Attempto_Controlled_English

Tatum011909/07 22:57很棒 推

iwillbehere09/08 13:57

謝謝 :)

※ 編輯: AmosYang (136.56.13.184 美國), 09/09/2020 20:48:53

ygl0118109/14 07:32

NCUcsie10509/15 08:29

謝謝 :)

※ 編輯: AmosYang (136.56.13.184 美國), 09/18/2020 12:17:29