PTT職涯區 / Soft_Job (軟體人)

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

看板Soft_Job (軟體人)作者 (艾倫王十五)時間7年前 (2018/05/08 10:18), 7年前編輯推噓54(54推 0噓 33→)
留言87則, 59人參與, 7年前最新討論串1/1
大家好，有一些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
推
05/08 10:35, 7年前 , 1F
我是直接參考微軟的: 開發類別庫的設計方針
05/08 10:35, 1F
→
05/08 12:06, 7年前 , 2F
準備雞排先
05/08 12:06, 2F
推
05/08 12:29, 7年前 , 3F
推
05/08 12:29, 3F
推
05/08 12:36, 7年前 , 4F
中間有個小錯字deadline 唷
05/08 12:36, 4F
推
05/08 12:42, 7年前 , 5F
你菜蟲掉到地上了
05/08 12:42, 5F
→
05/08 12:51, 7年前 , 6F
公司不是都會規範嗎
05/08 12:51, 6F
推
05/08 12:54, 7年前 , 7F
推
05/08 12:54, 7F
推
05/08 13:00, 7年前 , 8F
推
05/08 13:00, 8F
推
05/08 13:03, 7年前 , 9F
推推
05/08 13:03, 9F
推
05/08 13:19, 7年前 , 10F
回樓上 公司規範跟知道訂規範後面的原因是兩件事啊
05/08 13:19, 10F
※ 編輯: allenwang15 (123.51.169.72), 05/08/2018 13:30:31
推
05/08 13:32, 7年前 , 11F
勒布朗OP
05/08 13:32, 11F
※ 編輯: allenwang15 (123.51.169.72), 05/08/2018 13:36:38
推
05/08 14:34, 7年前 , 12F
推 不過iPhone用JPTT編輯很猛耶
05/08 14:34, 12F
推
05/08 14:44, 7年前 , 13F
用中文沒煩惱(誤
05/08 14:44, 13F
推
05/08 15:11, 7年前 , 14F
Re: 動詞，可參考我這篇 #1Qi4OxGH (Soft_Job) 裡的參
05/08 15:11, 14F
→
05/08 15:11, 7年前 , 15F
考資料: 「微軟 PowerShell 指令動詞列表」
05/08 15:11, 15F
推
05/08 15:33, 7年前 , 16F
居然還沒戰起來@@
05/08 15:33, 16F
→
05/08 15:41, 7年前 , 17F
很不錯收起來了
05/08 15:41, 17F
推
05/08 16:26, 7年前 , 18F
code complete 有一整個章節在講這種
05/08 16:26, 18F
推
05/08 16:52, 7年前 , 19F
推
05/08 16:52, 19F
推
05/08 17:53, 7年前 , 20F
推推~
05/08 17:53, 20F
推
05/08 18:08, 7年前 , 21F
推
05/08 18:08, 21F
推
05/08 18:35, 7年前 , 22F
補充動詞：parse
05/08 18:35, 22F
推
05/08 19:29, 7年前 , 23F
bindEvents()
05/08 19:29, 23F
→
05/08 19:39, 7年前 , 24F
我都用匈牙利命名法
05/08 19:39, 24F
→
05/08 19:40, 7年前 , 25F
而coding style則採用java style(我會被oracle告嗎?)
05/08 19:40, 25F
推
05/08 19:49, 7年前 , 26F
有同事之前被雕function不懂 然後他不爽就下次命名打Fu
05/08 19:49, 26F
→
05/08 19:49, 7年前 , 27F
ckyouXXX XXX是function
05/08 19:49, 27F
推
05/08 20:09, 7年前 , 28F
我的原則就是命名越短越好
05/08 20:09, 28F
推
05/08 21:00, 7年前 , 29F
推
05/08 21:00, 29F
推
05/08 21:06, 7年前 , 30F
如果是寫Objective-C的話這蠻自然就會了 有些人會覺
05/08 21:06, 30F
→
05/08 21:07, 7年前 , 31F
得這樣很囉說 但我是覺得方法名稱念起來就想在念一段
05/08 21:07, 31F
→
05/08 21:07, 7年前 , 32F
英文 還蠻直覺的
05/08 21:07, 32F
推
05/08 22:00, 7年前 , 33F
推 整理的好文
05/08 22:00, 33F
→
05/08 22:30, 7年前 , 34F
isMan 以前有人跟我說如果要省時就別先判斷XD
05/08 22:30, 34F
推
05/08 22:32, 7年前 , 35F
推好文！
05/08 22:32, 35F
推
05/08 22:36, 7年前 , 36F
推好文
05/08 22:36, 36F
推
05/08 22:40, 7年前 , 37F
推 \
05/08 22:40, 37F
→
05/08 22:53, 7年前 , 38F
匈牙利命名法是mUser這種嗎... 說實在我不太懂為什麼這樣不乾
05/08 22:53, 38F
推
05/08 22:54, 7年前 , 39F
我比較想問各位 變數命名時候 假使是英文單字過長
05/08 22:54, 39F
→
05/08 22:54, 7年前 , 40F
通常大家都怎麼縮寫...比較常有這困擾
05/08 22:54, 40F
→
05/08 22:55, 7年前 , 41F
脆取user算了=..=
05/08 22:55, 41F
推
05/08 22:58, 7年前 , 42F
之前 CSS 用縮寫，隔個星期就會忘記那是三小了
05/08 22:58, 42F
→
05/08 22:58, 7年前 , 43F
後來都不縮
05/08 22:58, 43F
推
05/08 23:00, 7年前 , 44F
推
05/08 23:00, 44F
推
05/08 23:15, 7年前 , 45F
很不錯
05/08 23:15, 45F
推
05/08 23:19, 7年前 , 46F
英文單字過長就宣告的旁邊加個註解？我是這樣拉
05/08 23:19, 46F
→
05/08 23:20, 7年前 , 47F
一樣縮寫就是了
05/08 23:20, 47F
推
05/08 23:35, 7年前 , 48F
第8點，直接在user寫一個isMan()的函式即可
05/08 23:35, 48F
推
05/08 23:36, 7年前 , 49F
推分享
05/08 23:36, 49F
推
05/08 23:37, 7年前 , 50F
可參考 Google Java style guide: https://goo.gl/z2SrCQ
05/08 23:37, 50F
推
05/08 23:44, 7年前 , 51F
推用心
05/08 23:44, 51F
推
05/09 00:03, 7年前 , 52F
其實不用刻意縮寫阿 真的很容易看不懂
05/09 00:03, 52F
推
05/09 01:18, 7年前 , 53F
過長就過長啊 我自己是喜歡在單字前加上型別
05/09 01:18, 53F
→
05/09 01:19, 7年前 , 54F
雖然clean code說別這樣用 但是用自動完成很方便
05/09 01:19, 54F
→
05/09 01:19, 7年前 , 55F
就算要改型別 直接右鍵重構就好了
05/09 01:19, 55F
→
05/09 01:21, 7年前 , 56F
或是一些控制項 combobox用cb開頭 textbox用tb開頭
05/09 01:21, 56F
推
05/09 03:13, 7年前 , 57F
先推+收藏XD
05/09 03:13, 57F
推
05/09 07:54, 7年前 , 58F
推
05/09 07:54, 58F
→
05/09 09:21, 7年前 , 59F
推
05/09 09:21, 59F
推
05/09 09:34, 7年前 , 60F
推
05/09 09:34, 60F
推
05/09 09:44, 7年前 , 61F
推
05/09 09:44, 61F
推
05/09 10:01, 7年前 , 62F
我喜歡推文就放得下的程式碼，這是multi-switch \ m s --
05/09 10:01, 62F
→
05/09 10:01, 7年前 , 63F
: mmatch >r ( swap r@ swap s:search null? if 2drop
05/09 10:01, 63F
→
05/09 10:02, 7年前 , 64F
drop else drop swap w:exec then ) m:each drop rdrop ;
05/09 10:02, 64F
推
05/09 10:30, 7年前 , 65F
推
05/09 10:30, 65F
推
05/09 11:14, 7年前 , 66F
推
05/09 11:14, 66F
推
05/09 18:12, 7年前 , 67F
推
05/09 18:12, 67F
→
05/09 21:48, 7年前 , 68F
變數活不過一頁的用小寫和底線串，活不過一個函數範圍的
05/09 21:48, 68F
→
05/09 21:50, 7年前 , 69F
，用駝峰式命名法。全域變數用底線當開頭，全域靜態變數
05/09 21:50, 69F
→
05/09 21:51, 7年前 , 70F
用全大寫。簡單的說看變數長怎樣，就知道這個變數的存活
05/09 21:51, 70F
→
05/09 21:52, 7年前 , 71F
範圍。至於命名方法看規定，上面的方法都有可能碰到。
05/09 21:52, 71F
推
05/09 22:46, 7年前 , 72F
實用推
05/09 22:46, 72F
推
05/10 00:22, 7年前 , 73F
推
05/10 00:22, 73F
推
05/10 09:12, 7年前 , 74F
感覺是從The art of readable code這本書整理的, 謝
05/10 09:12, 74F
→
05/10 09:12, 7年前 , 75F
原po整理
05/10 09:12, 75F
推
05/12 00:15, 7年前 , 76F
一個概念只用一個字滿重要的，我有時候會從同義字典裡挑
05/12 00:15, 76F
→
05/12 00:16, 7年前 , 77F
如果還是無法讓別人一眼就了解概念就再加註解
05/12 00:16, 77F
→
05/12 00:17, 7年前 , 78F
另外也可以 google 一下別人都用哪個字來表達同樣的概念
05/12 00:17, 78F
推
05/12 13:10, 7年前 , 79F
推
05/12 13:10, 79F
推
05/12 22:17, 7年前 , 80F
推
05/12 22:17, 80F
推
05/13 10:06, 7年前 , 81F
推
05/13 10:06, 81F
推
05/14 01:36, 7年前 , 82F
我遇到真的本身太長的英文單字都會Google abbreviation
05/14 01:36, 82F
→
05/14 01:40, 7年前 , 83F
以前也愛用handle 可最近想想handle 這字什麼意思也沒說
05/14 01:40, 83F
→
05/14 01:40, 7年前 , 84F
所以如果按鈕是要show dialog
05/14 01:40, 84F
→
05/14 01:40, 7年前 , 85F
我就用shoeDialog 不會用handleClick
05/14 01:40, 85F
→
05/14 21:21, 7年前 , 86F
最後一題，命名是跟著你的英文字彙量改變的，而不是定幾
05/14 21:21, 86F
→
05/14 21:21, 7年前 , 87F
個每次都拿來套用，單字認識多，就會找到最適合的語意。
05/14 21:21, 87F
‣ 更多 allenwang15 的文章
文章代碼(AID): #1QyGZx1s (Soft_Job)
Soft_Job 近期熱門文章
更多 近期熱門文章 >>
PTT職涯區 即時熱門文章
更多 即時熱門文章 >>
‣ 更多 allenwang15 的文章
文章代碼(AID): #1QyGZx1s (Soft_Job)