[請益] 程式的命名與coding style討論

[allenwang15 (艾倫王十五)]

大家好，有一些coding style的議題想跟各位分享與討論

勒布朗克法則(LeBlanc’s Law)説：Later equals Never
你心想著待會兒再回來整理程式，但其實永遠不會再回頭改的

最近想要整理出一些guideline跟同仁分享，
想說這樣大家的程式可讀性提升，對團隊的合作會更好，
不過我想先拋磚引玉，分享一些我整理出來的心得，
希望大大們可以分享一下自己的coding style
或是有更好或更多的撰寫程式的規範跟原則。

======================================

下方先是我整理的資料分享，歡迎大家也分享自己的coding style

1. Boolean變數或function的命名方式

Boolean變數或function的開頭必須使用is, can, has, should，
但如果本身是形容就不需要，像是enabled, done就無需用is開頭


2. 用介系詞(of,for,from,on…)來組變數名稱

這件事情但起來單純，但很多時候大家都會忽視介系詞硬組變數名稱，
像是daysUntilDeadline就有可能被命名成DeadlineDays，如易造成誤解，
以下是我找到一些不錯的範例

var daysSinceModification = 3; // 在修改已過了3天
var workDaysPerWeek = 5; // 每週工作5天
var daysUntilDeadline = 10; // deadline前還剩10天


3.使用更具體的單位

delayedTime代表的是delay的時間，但其實單位是秒數，
所以命名上最好使用更具體的單位來優化這個命名，改寫成delayedSeconds會更好


4.捨棄i,j,k，使用更好的Iterator
一般for迴圈中我們都會使用到i, j, k，這其實不是不行，
但是如果i, j, k分別代表parent, children, toy，
那就可以用pi, ci, ti來取代i, j, k，這樣程式碼不會變長太多，
可讀性提高也較容易debug


5.Function Name的prefix都是動詞

基本上function名稱全都是「動詞」
開頭但如果像是getCellSize()或calcCellSize()，可以直接省略開頭的動詞，
直接使用cellSize()即可，不過也有人堅持不能用名詞開頭，基本上團隊統一即可。


6.縮寫真的方便但並不是最好

因為不想打太長的變數或函數名稱，大家總是在縮寫，
但是有些縮寫很容易讓人搞混，對於原本就在維護這份程式的工程師或許還好，
但新進工程師會很容易困惑。

使用像是dns,url這些眾所皆知的詞沒問題，只有自己團隊才看得懂的縮寫，
除非必要，不然盡量避免使用。

不過我覺得這個看情況而定，重點是一定要有一份解釋縮寫的文件比較好。


7.如何寫註解

＊在檔案的最前頭寫上整個程式檔案大致是如何運作的檔案註解

＊除了解釋程式運作的原理外，還可以描述為什麼要用這樣子的寫法來寫，
  可能是效能上的需求之類的

＊使用 TODO FIXME 等註解標籤，TODO可以標記尚未製作或是需要優化的部分，
  FIXME是不能運作需要修復的部分，其實我知道還有HACK, XXX 等標籤，
  不過我覺得好像都歸類在TODO比較方便，不知道大家的習慣是如何？

＊在設定常數的時候給予註解其實也能幫助理解，讓開發者更有概念，
  像是下面程式註解說明為什麼要設定為1000的理由

  // 加上合理的限制 - 沒有人能讀那麼多文章
  const int MAX_RSS_SUBSCRIPTIONS = 1000;


8.封裝條件

如果if()裡面有超長一串的判斷式，可讀性會超差，
所以可以把這個判斷式用boolean變數裝起來再判斷

boolean isMan = (user.age >= 18 && user.gender == ‘male’);

if (isMan){
    // 做一位男人該做的事 >///<
}

======================================

其中最想請教大家的是function前方動詞的分類

Clean Code這本書上有說
Pick one word for one abstract concept and stick with it.

不過比較沒人整理出較為通用的詞庫對應表，
我知道這個本來就沒官方解答，但是我想聽聽看各位的經驗，
整理出我自己的一套詞庫，以下是我目前整裡的詞庫


fetch：從遠端(透過API)獲取資料，例如：fetchUsers()

load：從本地端加載資料，例如：loadFile()

calculate/calc：通過計算獲取資料，例如：calcBMI()

show：顯示物件，如showModal()、showDialog()

remove：將資料之間的關係移除，資料本身還是會存在

delete/destroy：將資料刪除，資料將會不存在

on：定義event的時候使用，像是onClick,onChange

handle：當onClick之類的event發生時所觸發的function，
        例如：handleClick，如果click後面有受詞的話，
        這將受詞移到click前方* 例如：handleButtonClick


剩下還有哪些詞是大家常用的呢？還請各位大大不吝分享，
我在下面放一些可能會用到的詞，大家是怎麼給這些詞定義他專屬的concept，
或是有哪些沒提到的也可以補充一下，麻煩大家給點意見了XD

get/set
create: insert append add append
edit: modify update
complete: finish done end
send:   deliver, dispatch, announce, distribute, route
find:   search, extract, locate, recover
start:  launch, create, begin, open
make:   create, set upm build, genernate, compose, add, new

-----
Sent from JPTT on my iPhone

--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 223.140.152.183
※ 文章網址: https://www.ptt.cc/bbs/Soft_Job/M.1525745915.A.076.html
※ 編輯: allenwang15 (123.51.169.72), 05/08/2018 10:27:45
推 t64141: 我是直接參考微軟的: 開發類別庫的設計方針
→ johnny94: 準備雞排先
推 v9290026: 推
推 xji4m3: 中間有個小錯字deadline 唷
推 del680202: 你菜蟲掉到地上了
→ b81314: 公司不是都會規範嗎
推 evan176: 推
推 stfang925: 推
推 ap954212: 推推
推 Masakiad: 回樓上 公司規範跟知道訂規範後面的原因是兩件事啊
※ 編輯: allenwang15 (123.51.169.72), 05/08/2018 13:30:31
推 Argos: 勒布朗OP
※ 編輯: allenwang15 (123.51.169.72), 05/08/2018 13:36:38
推 hazih: 推 不過iPhone用JPTT編輯很猛耶
推 a926: 用中文沒煩惱(誤
推 AmosYang: Re: 動詞，可參考我這篇 #1Qi4OxGH (Soft_Job) 裡的參
→ AmosYang: 考資料: 「微軟 PowerShell 指令動詞列表」
推 qqkerk: 居然還沒戰起來@@
→ menshuei: 很不錯收起來了
推 NCUking: code complete 有一整個章節在講這種
推 jay123peter: 推
推 oas: 推推~
推 crazybad: 推
推 x51811danny: 補充動詞：parse
推 paulshain04: bindEvents()
→ eva19452002: 我都用匈牙利命名法
→ eva19452002: 而coding style則採用java style(我會被oracle告嗎?)
推 mikejhou: 有同事之前被雕function不懂 然後他不爽就下次命名打Fu
→ mikejhou: ckyouXXX XXX是function
推 O187: 我的原則就是命名越短越好
推 louis70109: 推
推 tom19830924: 如果是寫Objective-C的話這蠻自然就會了 有些人會覺
→ tom19830924: 得這樣很囉說 但我是覺得方法名稱念起來就想在念一段
→ tom19830924: 英文 還蠻直覺的
推 shiauji: 推 整理的好文
→ pigcat1315: isMan 以前有人跟我說如果要省時就別先判斷XD
推 ymcheung: 推好文！
推 yupog2003: 推好文
推 bill0205: 推 \
→ y3k: 匈牙利命名法是mUser這種嗎... 說實在我不太懂為什麼這樣不乾
推 bill0205: 我比較想問各位 變數命名時候 假使是英文單字過長
→ bill0205: 通常大家都怎麼縮寫...比較常有這困擾
→ y3k: 脆取user算了=..=
推 ymcheung: 之前 CSS 用縮寫，隔個星期就會忘記那是三小了
→ ymcheung: 後來都不縮
推 e920528: 推
推 rollr: 很不錯
推 yupog2003: 英文單字過長就宣告的旁邊加個註解？我是這樣拉
→ yupog2003: 一樣縮寫就是了
推 akai1024: 第8點，直接在user寫一個isMan()的函式即可
推 ID3238: 推分享
推 tailau0: 可參考 Google Java style guide: https://goo.gl/z2SrCQ
推 hiJackylin: 推用心
推 pigcat1315: 其實不用刻意縮寫阿 真的很容易看不懂
推 vi000246: 過長就過長啊 我自己是喜歡在單字前加上型別
→ vi000246: 雖然clean code說別這樣用 但是用自動完成很方便
→ vi000246: 就算要改型別 直接右鍵重構就好了
→ vi000246: 或是一些控制項 combobox用cb開頭 textbox用tb開頭
推 CaLeLu: 先推+收藏XD
推 wanlinlin: 推
→ dm33: 推
推 ppppman: 推
推 wilson85771: 推
推 enthos: 我喜歡推文就放得下的程式碼，這是multi-switch \ m s --
→ enthos: : mmatch >r ( swap r@ swap s:search null? if 2drop
→ enthos: drop else drop swap w:exec then ) m:each drop rdrop ;
推 DingDang827: 推
推 dogalan: 推
推 tz5514: 推
→ AvatarH: 變數活不過一頁的用小寫和底線串，活不過一個函數範圍的
→ AvatarH: ，用駝峰式命名法。全域變數用底線當開頭，全域靜態變數
→ AvatarH: 用全大寫。簡單的說看變數長怎樣，就知道這個變數的存活
→ AvatarH: 範圍。至於命名方法看規定，上面的方法都有可能碰到。
推 wifirts: 實用推
推 pardo: 推
推 Raymond0710: 感覺是從The art of readable code這本書整理的, 謝
→ Raymond0710: 原po整理
推 CRPKT: 一個概念只用一個字滿重要的，我有時候會從同義字典裡挑
→ CRPKT: 如果還是無法讓別人一眼就了解概念就再加註解
→ CRPKT: 另外也可以 google 一下別人都用哪個字來表達同樣的概念
推 overhead: 推
推 chendkkkk: 推
推 moon2519: 推
推 Ghamu: 我遇到真的本身太長的英文單字都會Google abbreviation
→ Ghamu: 以前也愛用handle 可最近想想handle  這字什麼意思也沒說
→ Ghamu: 所以如果按鈕是要show dialog
→ Ghamu: 我就用shoeDialog 不會用handleClick
→ ChoDino: 最後一題，命名是跟著你的英文字彙量改變的，而不是定幾
→ ChoDino: 個每次都拿來套用，單字認識多，就會找到最適合的語意。