PTT動漫區 / C_Chat (希洽)

Re: [閒聊] 寫code不加註解真的很顧人怨嗎

看板C_Chat (希洽)作者 (竹鼠)時間22小時前 (2024/12/25 21:04), 編輯推噓30(31推 1噓 63→)
留言95則, 35人參與, 12小時前最新討論串4/5 (看更多)
以下是根據本魯碼農自己的經驗，絕大部份參考Clean Code這本書，我自己是將這本書奉為 圭臬，不過我也知道很多人反對書裡的一些看法，所以聽聽就好 首先一個最大的原則就是程式碼必須好懂，因為它同時是寫給機器跟人看的，好懂是可擴充 性跟可維護性的必要，是程式碼無比重要的基石 推文有人說程式碼沒有註解的話十年後的自己會無法理解，實際上根據我自己的經驗如果我 寫出一段不好讀的程式碼，幾天、幾個小時甚至幾分鐘之後我就會痛恨之前的自己了 那麼註解是必要的嗎？我認為註解有其必要，但應該越少越好 為什麼越少越好呢？首先，程式碼應該要可以自己描述自己，來看一個簡單的範例： float multi(float a, float b) { return a*b; } 很容易就能看出這是一個做乘法的方法，但他的用處是什麼？沒人看得出來 float convertUsdToNtd(float usd, float converRatio) { return usd * convertRatio; } 這樣就一目了然了，這是一個把美金轉換成新台幣的方法，如此就不需要註解了。在實務上 ，尤其是在有複雜的業務邏輯的時候，變數跟方法名稱可能會長到惱人的地步，但為了可讀 性，這是必要的犧牲。 我們還能繼續擴充這個方法，例如說加入即時匯率，讓他可以將轉換幣值這件事做的更好 float convertUsdToNtd(float usd, FinaceService financeService) { return usd * finaceService.getUsdToNtdRatio; // Multiply usd and ratio. } 上面的程式碼有一行註解，但不難看出這個註解是一句廢話，因為他只是描述了該句程式碼 做了什麼。好的註解應該從抽象、高層次的方向來解釋程式碼的用意、為什麼要這麼寫： float convertUsdToNtd(float usd, FinaceService financeService) { // Fetch ratio from finance service for real time return usd * finaceService.getUsdToNtdRatio; } 上面的程式碼解釋了為什麼要從finance service 獲得匯率，因為必須要獲得當下即時的匯 率 但註解並不總是好的，有時候他可能是有害的。假設我今天修改了這個方法，讓他不再是根 據即時匯率，而是某一天的平均匯率： float convertUsdToNtdByDate(float usd, Date date, FinaceService financeService) { // Fetch ratio from finance service for real time return usd * finaceService.getUsdToNtdRatioByDate(date); } 程式碼更改但是註解忘了更新的情況下，這行註解就是錯的。錯誤的註解會造成混亂，低效 ，甚至錯誤！程式碼本身的可讀性重要性應該永遠高於註解，因為程式碼描述的就是事實， 你沒辦法寫出一行程式碼做的事情和他看起來的不同（Well, 通常沒辦法）但是註解可以！ 跟註解不同的是，我認為文件（document）是有必要而且多一點較好的，文件是寫在方法前 面的註解，用來描述這個方法做了什麼： /* Convert USD to NTD by ratio from a specific date. */ float convertUsdToNtdByDate(float usd, Date date, FinaceService financeService) { return usd * finaceService.getUsdToNtdRatioByDate(date); } 文件是讓下一份閱讀程式碼的人（通常就是你自己）快速理解這個方法是做什麼，他會輸入 什麼，他會回傳什麼最好的方式。文件只會從最抽象的層次描述方法，不會包含任何的實作 細節，除非這個細節有必要讓使用者知道（例如說，某些情況下的演算法和其時間複雜度） 。而且我認為應該要採用文件導向的方式-當你創建新的方法時，你應該先編寫文件修改時 亦同 ※ 引述《ianlin1216 (伊恩可可)》之銘言 : 餓死抬頭 : https://i.imgur.com/3QcIsVN.jpeg
: 本魯不是資工系的啦 : 所以不知道寫程式不加註解會有多嚴重 : 想請問相關從業的鄉民 : 實務上遇到這種情況真的很賭爛嗎 : 乾五西恰 -- ※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 42.75.8.221 (臺灣) ※ 文章網址: https://www.ptt.cc/bbs/C_Chat/M.1735131856.A.AB0.html
→
12/25 21:06, 22小時前 , 1F
首先算錢用浮點
12/25 21:06, 1F
推
12/25 21:07, 22小時前 , 2F
反對者很多 而且還很大一部份是不學無術的老屁股冗員
12/25 21:07, 2F
→
12/25 21:07, 22小時前 , 3F
因為寫clean code很麻煩 很燒腦 很吃力不討好 懶啦
12/25 21:07, 3F
推
12/25 21:07, 22小時前 , 4F
原來寫在 function 前的comment還有特別稱呼啊XD
12/25 21:07, 4F
噓
12/25 21:10, 22小時前 , 5F
西洽點在哪
12/25 21:10, 5F
推
12/25 21:10, 22小時前 , 6F
所以是建議用大寫區隔函式內的詞而不是底線嗎
12/25 21:10, 6F
→
12/25 21:10, 22小時前 , 7F
我知道算錢有更好的方式，但我不想加入太多東西讓這篇
12/25 21:10, 7F
→
12/25 21:10, 22小時前 , 8F
文章對新手來說更難懂
12/25 21:10, 8F
推
12/25 21:11, 22小時前 , 9F
推文件導向
12/25 21:11, 9F
→
12/25 21:12, 22小時前 , 10F
回文不用點
12/25 21:12, 10F
→
12/25 21:12, 22小時前 , 11F
回文不是不用點 而是沒有洽點的話要跟引文有關係
12/25 21:12, 11F
→
12/25 21:12, 22小時前 , 12F
命名風格通常是根據程式語言跟你的團隊來做決定，以這
12/25 21:12, 12F
→
12/25 21:12, 22小時前 , 13F
篇文來說是Java
12/25 21:12, 13F
→
12/25 21:13, 22小時前 , 14F
這篇顯然是跟引文有關的
12/25 21:13, 14F
推
12/25 21:16, 22小時前 , 15F
回文又不用點 鬼叫什麼
12/25 21:16, 15F
推
12/25 21:16, 22小時前 , 16F
前面的那個不完全是comment，有的說法是doc string。
12/25 21:16, 16F
→
12/25 21:17, 22小時前 , 17F
像是Python有"""開頭"""結尾可以寫整串的東西能用。
12/25 21:17, 17F
推
12/25 21:17, 22小時前 , 18F
總之好懂的寫法就是對的，想辦法寫出好懂的程式也是對的
12/25 21:17, 18F
→
12/25 21:17, 22小時前 , 19F
我一直以為這些都叫做 comment XDDD
12/25 21:17, 19F
→
12/25 21:17, 22小時前 , 20F
這篇是正確的，可以自我註釋的程式碼才好讀
12/25 21:17, 20F
→
12/25 21:18, 22小時前 , 21F
Rust有///開頭的東西，編譯同時可以輸出成文件。
12/25 21:18, 21F
推
12/25 21:18, 22小時前 , 22F
推這篇
12/25 21:18, 22F
→
12/25 21:19, 22小時前 , 23F
我現在常常只寫註解就讓GenAI跑程式出來
12/25 21:19, 23F
→
12/25 21:19, 22小時前 , 24F
如果函數切分得好，函數名稱本身就是一個好的註解了。
12/25 21:19, 24F
推
12/25 21:19, 22小時前 , 25F
算錢也不能用浮點，用decimal才能避免小數點問題
12/25 21:19, 25F
→
12/25 21:20, 22小時前 , 26F
很多語言甚至不同TEAM的規範都不同吧 這我倒是覺得統一就好
12/25 21:20, 26F
→
12/25 21:20, 22小時前 , 27F
大寫區隔函式內的詞??
12/25 21:20, 27F
→
12/25 21:20, 22小時前 , 28F
你是想說 camel case ??
12/25 21:20, 28F
→
12/25 21:21, 22小時前 , 29F
每個語言基本代碼風格規範不同這看起來是C#
12/25 21:21, 29F
→
12/25 21:21, 22小時前 , 30F
這是JAVA阿
12/25 21:21, 30F
推
12/25 21:22, 22小時前 , 31F
C/C++ 是不是也是這個樣子啊？
12/25 21:22, 31F
→
12/25 21:22, 22小時前 , 32F
真的欸 那他在說什麼大寫
12/25 21:22, 32F
→
12/25 21:22, 22小時前 , 33F
C#的命名風格是函數PascalCase，區域變數才用camelCase。
12/25 21:22, 33F
→
12/25 21:23, 22小時前 , 34F
這個變數命名那個自己組裡面講好就好了 然後寫的時候看
12/25 21:23, 34F
→
12/25 21:23, 22小時前 , 35F
一下有沒有跟旁邊的code長得太不一樣XDDD
12/25 21:23, 35F
→
12/25 21:24, 22小時前 , 36F
推文應該只是不知道code style，那個各語言習慣差很多。
12/25 21:24, 36F
推
12/25 21:24, 22小時前 , 37F
反正不要用奇怪的縮寫或沒意義的詞就好
12/25 21:24, 37F
→
12/25 21:24, 22小時前 , 38F
有看過初學者用ABCDEFG來命名XD
12/25 21:24, 38F
→
12/25 21:25, 22小時前 , 39F
editorconfig解決縮排問題，coding style各語言各有工具。
12/25 21:25, 39F
→
12/25 21:25, 22小時前 , 40F
現在寫程式比以前好太多了，AI太強
12/25 21:25, 40F
→
12/25 21:26, 22小時前 , 41F
聽說打競賽的為了拚那幾秒，會用abc跟ijk這種免洗命名法XD
12/25 21:26, 41F
推
12/25 21:26, 22小時前 , 42F
變數名不要取太差就還好 真的
12/25 21:26, 42F
→
12/25 21:27, 22小時前 , 43F
12/25 21:27, 43F
→
12/25 21:28, 22小時前 , 44F
有些26會用漢語拼音+縮寫=通靈命名法
12/25 21:28, 44F
→
12/25 21:29, 22小時前 , 45F
y1s1 對岸應該很習慣
12/25 21:29, 45F
推
12/25 21:30, 22小時前 , 46F
我一直想知道中國工程師寫int64會不會過不了審
12/25 21:30, 46F
→
12/25 21:31, 22小時前 , 47F
不會 小學生看不懂
12/25 21:31, 47F
推
12/25 21:32, 22小時前 , 48F
26那邊真的很多拼音縮寫的智障命名法= =
12/25 21:32, 48F
→
12/25 21:32, 22小時前 , 49F
變數如何命名也是個大坑，一般來說你的視野（scope）越
12/25 21:32, 49F
→
12/25 21:32, 22小時前 , 50F
大，名稱就要越長，反之則最短
12/25 21:32, 50F
→
12/25 21:32, 22小時前 , 51F
scope很大，名稱很短會死人阿XDDD
12/25 21:32, 51F
→
12/25 21:33, 22小時前 , 52F
5樓菜雞還特別大聲
12/25 21:33, 52F
推
12/25 21:34, 22小時前 , 53F
所以一般會用namespace保護啊
12/25 21:34, 53F
推
12/25 21:48, 21小時前 , 54F
但C沒有namespace，不是在.c能用static藏的函數得很臭長。
12/25 21:48, 54F
推
12/25 21:50, 21小時前 , 55F
沒有 namespace ... 好ㄅ
12/25 21:50, 55F
→
12/25 21:54, 21小時前 , 56F
原來如此
12/25 21:54, 56F
推
12/25 21:55, 21小時前 , 57F
其實大家指的「必須要存在的」 comment 就是原 Po 的 doc
12/25 21:55, 57F
→
12/25 21:55, 21小時前 , 58F
ument 吧
12/25 21:55, 58F
→
12/25 21:55, 21小時前 , 59F
只是好像不是每個人都會這樣稱呼它，甚至我也只在 clean
12/25 21:55, 59F
→
12/25 21:55, 21小時前 , 60F
code 以及一些軟工討論才有機會看到這樣的稱呼
12/25 21:55, 60F
→
12/25 21:57, 21小時前 , 61F
C 因為沒有 namespace 所以 scope 更顯得重要就是了。幸
12/25 21:57, 61F
→
12/25 21:57, 21小時前 , 62F
好還是有 struct 這種基本的能用
12/25 21:57, 62F
→
12/25 22:01, 21小時前 , 63F
VS有內建的註解系統能搭配PLUGIN輸出成程式說明文件
12/25 22:01, 63F
→
12/25 22:02, 21小時前 , 64F
但認真寫會變成CODE以外一大堆又臭又長的XML註解 所以官方
12/25 22:02, 64F
→
12/25 22:03, 21小時前 , 65F
又建議你用另一個特殊的XML NODE把整份XML註解移動到一個獨
12/25 22:03, 65F
→
12/25 22:03, 21小時前 , 66F
立的XML檔案 然後程式碼只要指過去就好 但不知道有多少人真
12/25 22:03, 66F
→
12/25 22:04, 21小時前 , 67F
的有用這套XML註解功能產整份文件...
12/25 22:04, 67F
推
12/25 22:11, 21小時前 , 68F
推 clean code
12/25 22:11, 68F
推
12/25 22:29, 21小時前 , 69F
對，你全部都重寫當然沒問題
12/25 22:29, 69F
推
12/25 22:46, 20小時前 , 70F
推
12/25 22:46, 70F
推
12/25 23:00, 20小時前 , 71F
我自己經驗，一個禮拜這隻code就不認識了，有過看code覺得這
12/25 23:00, 71F
→
12/25 23:00, 20小時前 , 72F
個人寫的不錯，想法和我差不多，再看作者，靠北，不就是我自
12/25 23:00, 72F
→
12/25 23:00, 20小時前 , 73F
己，還上禮拜寫的 XD 忙的時候特別容易發生這種事情
12/25 23:00, 73F
推
12/25 23:23, 20小時前 , 74F
現代螢幕都夠大了取名長一點沒什麼問題 取很簡短又重複的在
12/25 23:23, 74F
→
12/25 23:23, 20小時前 , 75F
大型專案裡面搜關鍵字會很火
12/25 23:23, 75F
推
12/25 23:35, 20小時前 , 76F
推
12/25 23:35, 76F
推
12/25 23:36, 20小時前 , 77F
同意這篇
12/25 23:36, 77F
推
12/26 00:14, 19小時前 , 78F
算錢用浮點 遲早被人扁
12/26 00:14, 78F
推
12/26 00:56, 18小時前 , 79F
同意文件的優先重要性
12/26 00:56, 79F
→
12/26 00:56, 18小時前 , 80F
但如果遇到寫文件就像要他命的團隊...
12/26 00:56, 80F
→
12/26 00:56, 18小時前 , 81F
摸摸鼻子寫好ITS備註跟註解存證據比較快= =
12/26 00:56, 81F
→
12/26 01:02, 18小時前 , 82F
c 姑且算是有 ns 啦 只是人家的 ns 是劃在 compile unit 上
12/26 01:02, 82F
推
12/26 01:02, 18小時前 , 83F
推
12/26 01:02, 83F
→
12/26 01:02, 18小時前 , 84F
推
12/26 01:02, 84F
→
12/26 01:03, 18小時前 , 85F
所以會有那種同一個元件有兩個 header 一個內用一個外帶
12/26 01:03, 85F
→
12/26 01:42, 17小時前 , 86F
clean code 明明就蠻簡單的 講白了用代碼講清楚自己
12/26 01:42, 86F
→
12/26 01:42, 17小時前 , 87F
的代碼在幹嘛
12/26 01:42, 87F
推
12/26 02:18, 17小時前 , 88F
文件跟註解有一樣的問題 程式碼改了 功能有變化 文件
12/26 02:18, 88F
→
12/26 02:18, 17小時前 , 89F
不見得會更新 是說連註解都沒改了 文件更不會改
12/26 02:18, 89F
→
12/26 02:19, 17小時前 , 90F
但是寫文件跟維護文件很重要我舉雙手同意
12/26 02:19, 90F
→
12/26 02:21, 17小時前 , 91F
只是時程上往往沒有足夠的時間去維護文件
12/26 02:21, 91F
推
12/26 04:25, 15小時前 , 92F
推這篇 沒有code review已經夠怪了 連規範都沒有 不知道那種
12/26 04:25, 92F
→
12/26 04:25, 15小時前 , 93F
公司在幹嘛
12/26 04:25, 93F
推
12/26 07:41, 12小時前 , 94F
基本上文件先行 就沒有維護來不及的問題 再來就是如這篇
12/26 07:41, 94F
→
12/26 07:41, 12小時前 , 95F
所講 別誤用註解
12/26 07:41, 95F
‣ 更多 pride829 的文章
文章代碼(AID): #1dR0BGgm (C_Chat)
C_Chat 近期熱門文章
更多 近期熱門文章 >>
PTT動漫區 即時熱門文章
更多 即時熱門文章 >>
‣ 更多 pride829 的文章
文章代碼(AID): #1dR0BGgm (C_Chat)