Re: [閒聊] 寫code不加註解真的很顧人怨嗎
以下是根據本魯碼農自己的經驗，絕大部份參考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
: 所以不知道寫程式不加註解會有多嚴重
: 想請問相關從業的鄉民
: 實務上遇到這種情況真的很賭爛嗎
: 乾五西恰
--
首先算錢用浮點
反對者很多 而且還很大一部份是不學無術的老屁股冗員
因為寫clean code很麻煩 很燒腦 很吃力不討好 懶啦
原來寫在 function 前的comment還有特別稱呼啊XD
西洽點在哪
所以是建議用大寫區隔函式內的詞而不是底線嗎
我知道算錢有更好的方式，但我不想加入太多東西讓這篇
文章對新手來說更難懂
推文件導向
回文不用點
回文不是不用點 而是沒有洽點的話要跟引文有關係
命名風格通常是根據程式語言跟你的團隊來做決定，以這
篇文來說是Java
這篇顯然是跟引文有關的
回文又不用點 鬼叫什麼
前面的那個不完全是comment，有的說法是doc string。
像是Python有"""開頭"""結尾可以寫整串的東西能用。
總之好懂的寫法就是對的，想辦法寫出好懂的程式也是對的
我一直以為這些都叫做 comment XDDD
這篇是正確的，可以自我註釋的程式碼才好讀
Rust有///開頭的東西，編譯同時可以輸出成文件。
推這篇
我現在常常只寫註解就讓GenAI跑程式出來
如果函數切分得好，函數名稱本身就是一個好的註解了。
算錢也不能用浮點，用decimal才能避免小數點問題
很多語言甚至不同TEAM的規範都不同吧 這我倒是覺得統一就好
大寫區隔函式內的詞??
你是想說 camel case ??
每個語言基本代碼風格規範不同這看起來是C#
這是JAVA阿
C/C++ 是不是也是這個樣子啊？
真的欸 那他在說什麼大寫
C#的命名風格是函數PascalCase，區域變數才用camelCase。
這個變數命名那個自己組裡面講好就好了 然後寫的時候看
一下有沒有跟旁邊的code長得太不一樣XDDD
推文應該只是不知道code style，那個各語言習慣差很多。
反正不要用奇怪的縮寫或沒意義的詞就好
有看過初學者用ABCDEFG來命名XD
editorconfig解決縮排問題，coding style各語言各有工具。
現在寫程式比以前好太多了，AI太強
聽說打競賽的為了拚那幾秒，會用abc跟ijk這種免洗命名法XD
變數名不要取太差就還好 真的
有些26會用漢語拼音+縮寫=通靈命名法
y1s1 對岸應該很習慣
我一直想知道中國工程師寫int64會不會過不了審
不會 小學生看不懂
26那邊真的很多拼音縮寫的智障命名法= =
變數如何命名也是個大坑，一般來說你的視野（scope）越
大，名稱就要越長，反之則最短
scope很大，名稱很短會死人阿XDDD
5樓菜雞還特別大聲
所以一般會用namespace保護啊
但C沒有namespace，不是在.c能用static藏的函數得很臭長。
沒有 namespace ... 好ㄅ
原來如此
其實大家指的「必須要存在的」 comment 就是原 Po 的 doc
ument 吧
只是好像不是每個人都會這樣稱呼它，甚至我也只在 clean
code 以及一些軟工討論才有機會看到這樣的稱呼
C 因為沒有 namespace 所以 scope 更顯得重要就是了。幸
好還是有 struct 這種基本的能用
VS有內建的註解系統能搭配PLUGIN輸出成程式說明文件
但認真寫會變成CODE以外一大堆又臭又長的XML註解 所以官方
又建議你用另一個特殊的XML NODE把整份XML註解移動到一個獨
立的XML檔案 然後程式碼只要指過去就好 但不知道有多少人真
的有用這套XML註解功能產整份文件...
推 clean code
對，你全部都重寫當然沒問題
推
我自己經驗，一個禮拜這隻code就不認識了，有過看code覺得這
個人寫的不錯，想法和我差不多，再看作者，靠北，不就是我自
己，還上禮拜寫的 XD 忙的時候特別容易發生這種事情
現代螢幕都夠大了取名長一點沒什麼問題 取很簡短又重複的在
大型專案裡面搜關鍵字會很火
推
同意這篇
算錢用浮點 遲早被人扁
同意文件的優先重要性
但如果遇到寫文件就像要他命的團隊...
摸摸鼻子寫好ITS備註跟註解存證據比較快= =
c 姑且算是有 ns 啦 只是人家的 ns 是劃在 compile unit 上
推
推
所以會有那種同一個元件有兩個 header 一個內用一個外帶
clean code 明明就蠻簡單的 講白了用代碼講清楚自己
的代碼在幹嘛
文件跟註解有一樣的問題 程式碼改了 功能有變化 文件
不見得會更新 是說連註解都沒改了 文件更不會改
但是寫文件跟維護文件很重要我舉雙手同意
只是時程上往往沒有足夠的時間去維護文件
推這篇 沒有code review已經夠怪了 連規範都沒有 不知道那種
公司在幹嘛
基本上文件先行 就沒有維護來不及的問題 再來就是如這篇
所講 別誤用註解
爆
首Po餓死抬頭 本魯不是資工系的啦 所以不知道寫程式不加註解會有多嚴重 想請問相關從業的鄉民![[閒聊] 寫code不加註解真的很顧人怨嗎](https://i.imgur.com/3QcIsVNb.jpeg "[閒聊] 寫code不加註解真的很顧人怨嗎")
59
大家好 我月薪28k軟體工程師啦 我的觀察齁 程式設計師有好幾種類型 1. 無口型 做了很奇怪的事也不註解，commit也找不到原因 等到哪個有重構強迫症的改壞程式以後才發現原來看似很奇![Re: [閒聊] 寫code不加註解真的很顧人怨嗎](https://img.youtube.com/vi/dQw4w9WgXcQ/mqdefault.jpg "Re: [閒聊] 寫code不加註解真的很顧人怨嗎")
8
最好的作法是 盡量把程式寫得清楚簡單易懂好理解 這樣就不需要加註解了 註解是拿來用在解釋特殊情況 也就是![Re: [閒聊] 寫code不加註解真的很顧人怨嗎](https://www.redditstatic.com/shreddit/assets/favicon/192x192.png "Re: [閒聊] 寫code不加註解真的很顧人怨嗎")
21
真的有這麼奇葩的註解嗎 上 code 前不是都會做 code review 嗎 現在很多工具除了會做 style check，commit message 之外， 甚至有些工具會檢查註解是否符合格式吧 這種亂上 code 真的不會被幹到起飛嗎
26
[問卦] 程式碼中有簡體字註解的問題是什麼？各位駐八卦版工程師大家好 我朋友之前幫老闆做專案啊 在寫網頁前端，其中JavaScript的部份好像不太會寫 跑去對岸知名的網註CSDN直接複製程式碼來使用 沒想到交付客戶後，被客戶抓包裡面有簡體字的註解![[問卦] 程式碼中有簡體字註解的問題是什麼？](https://i.imgur.com/QdgH4VNb.jpg "[問卦] 程式碼中有簡體字註解的問題是什麼？")
18
[討論] 沒有SA、Mentor，新人該怎麼辦？安安，又是我！ 我已經在軟體公司實習了，不要說我都沒有行動了。 事情是這樣子的，我剛進去這間軟體公司的時候，問 裡面的資深學長有沒有Mentor，他說沒有。 之後主管交待我完成一些code，我問資深的學長有沒29
Re: [心得] 好的註解是解釋為何需要這段 code上週在重構某段程式碼時，其中一位同事在 code review 中建議把某個註解刪掉，另一 個同事看到這個評論時，在下面留了言說他認為不應該刪掉，於是我們就拉了一個小討論 ，聊在程式碼中寫註解這件事。 因為這個經驗，我回去重翻史丹佛電腦科學教授 John Ousterhout 寫的《A Philosophy of Software Design》一書，並整理了筆記。該教授的觀點是認為程式碼寫註解有很多好![Re: [心得] 好的註解是解釋為何需要這段 code](https://www.explainthis.io/static/images/twitter-card.png "Re: [心得] 好的註解是解釋為何需要這段 code")
11
Re: [新聞] 五倍券網站見簡體字 王美花:絕對沒有資安說真的，註解也是程式碼的一部分阿 問國小的孩子可能都可以講出正確的答案 部長這樣的發言，幕僚有沒有捏一把冷汗? 然後念資工的高立委，會放過她嗎? 有沒有部長不知道【寫好程式的第一步就是寫好註解】的八卦呢?![Re: [新聞] 五倍券網站見簡體字 王美花:絕對沒有資安](https://i.imgur.com/a4hgT98b.jpg "Re: [新聞] 五倍券網站見簡體字 王美花:絕對沒有資安")
11
Re: [閒聊] OPENAI出現前，OPENAI出現後ChatGPT生成程式碼 - 5分鐘 除錯 - 24小時 你把這段改成 Google找答案複製程式碼 - 5分鐘 除錯 - 24小時![Re: [閒聊] OPENAI出現前，OPENAI出現後](https://pbs.twimg.com/media/Gc0l8jabsAAAau0.jpg "Re: [閒聊] OPENAI出現前，OPENAI出現後")
5
Re: [問卦] chatGPT是不是會消滅一堆文組職業？現在 vs code 已經可以整合 GPT-3 的 API 了。 直接選擇一段程式碼，讓 AI 自動生成註解； 或是反過來，先寫註解讓 AI 產生程式。 也可以直接跟AI聊天。 不分文理組，大家都可以洗洗睡了。3
Re: [閒聊] OPENAI出現前，OPENAI出現後"寫註解" 這個其實我覺得 Copilot 比 Intellisense 強最多的地方 就好像 Autocompletion的機能延伸到了寫註解上面 打程式的時候用到的頻率滿高的 現在不少LLM可以讀你的repo之後， 會回應你一些問題。不過大部分回應都滿罐頭的就是了![Re: [閒聊] OPENAI出現前，OPENAI出現後](https://i.imgur.com/ZsB6Y1Qb.jpg "Re: [閒聊] OPENAI出現前，OPENAI出現後")
爆
[閒聊] 刺客教條:暗影者 現在處境是不是很尷尬![[閒聊] 刺客教條:暗影者 現在處境是不是很尷尬](https://i.imgur.com/v9Asyreb.jpeg "[閒聊] 刺客教條:暗影者 現在處境是不是很尷尬")
68
[閒聊] 阿北收那麼多錢良心不會過意不去嗎？![[閒聊] 阿北收那麼多錢良心不會過意不去嗎？](https://i.imgur.com/QVKEMf2b.jpeg "[閒聊] 阿北收那麼多錢良心不會過意不去嗎？")
72
[問題] 動漫有沒有教會過你什麼哲理?![[問題] 動漫有沒有教會過你什麼哲理?](https://i.imgur.com/LGnlqxTb.jpeg "[問題] 動漫有沒有教會過你什麼哲理?")
65
[閒聊] 這幾款JRPG有比較推的嗎![[閒聊] 這幾款JRPG有比較推的嗎](https://img.youtube.com/vi/tdU4FdHoDc0/mqdefault.jpg "[閒聊] 這幾款JRPG有比較推的嗎")
39
[閒聊] FGO還有什麼大招可以開?![[閒聊] FGO還有什麼大招可以開?](https://i.imgur.com/e8dN5uAb.png "[閒聊] FGO還有什麼大招可以開?")
34
[GKMS] 佛心公司![[GKMS] 佛心公司](https://i.imgur.com/ASbNq8Ub.jpeg "[GKMS] 佛心公司")
29
[MYGO] 有錢的祥子人很溫柔耶![[MYGO] 有錢的祥子人很溫柔耶](https://i.imgur.com/XbOGMuqb.jpeg "[MYGO] 有錢的祥子人很溫柔耶")
22
[閒聊] 神樂鉢討論不起來嗎？18
[蔚藍] 一個人過聖誕的澪紗![[蔚藍] 一個人過聖誕的澪紗](https://i.imgur.com/rqBNKlib.jpeg "[蔚藍] 一個人過聖誕的澪紗")
16
[討論] 影之強者：現在才發現七影都未成年![[討論] 影之強者：現在才發現七影都未成年](https://i.imgur.com/YFHyOlPb.png "[討論] 影之強者：現在才發現七影都未成年")
16
[閒聊] 紅色店家指南：月讀女僕咖啡廳![[閒聊] 紅色店家指南：月讀女僕咖啡廳](https://i.imgur.com/tq85Dwbb.jpeg "[閒聊] 紅色店家指南：月讀女僕咖啡廳")
16
[東方] 東方入坑eratw16
[Vtub] 國中生Vtuber阿北樣樣自己來![[Vtub] 國中生Vtuber阿北樣樣自己來](https://img.youtube.com/vi/m8S6x3ce9rY/mqdefault.jpg "[Vtub] 國中生Vtuber阿北樣樣自己來")
15
[閒聊] mygo 13 完結灑花![[閒聊] mygo 13 完結灑花](https://i.imgur.com/V62whKRb.jpg "[閒聊] mygo 13 完結灑花")
15
[閒聊] 時間停止勇者 61 (雷)![[閒聊] 時間停止勇者 61 (雷)](https://imgpoi.com/i/X38VYV.png "[閒聊] 時間停止勇者 61 (雷)")
14
[活俠] 不要為了我而吵架！![[活俠] 不要為了我而吵架！](https://i.imgur.com/IZIIiXyb.jpg "[活俠] 不要為了我而吵架！")
14
[討論] 奈德要怎麼避免掉頭的結局？13
[閒聊] 重看落第騎士動畫 一刀羅剎還是蠻帥的13
Re: [情報] 合法成人內容也難逃「封殺」？日二次元![Re: [情報] 合法成人內容也難逃「封殺」？日二次元](https://img.youtube.com/vi/Ybcor1IyGeI/mqdefault.jpg "Re: [情報] 合法成人內容也難逃「封殺」？日二次元")
13
[問題] 東離第四季是不是不用急著補？11
[MyGO] 纏吻![[MyGO] 纏吻](https://i.imgur.com/FDTuryab.jpeg "[MyGO] 纏吻")
11
[閒聊] Atlus 橋野：過場使用動畫演出是因為適合![[閒聊] Atlus 橋野：過場使用動畫演出是因為適合](https://img.youtube.com/vi/jpXUDK1ejU0/mqdefault.jpg "[閒聊] Atlus 橋野：過場使用動畫演出是因為適合")
15
[閒聊] 魔戒洛汗人之戰吐槽和疑問(雷10
Re: [金毛] 純情大熊色情兔10
[MLTD]聖誕幼女中谷育降臨到我家![[MLTD]聖誕幼女中谷育降臨到我家](https://i.imgur.com/4rsPZk4b.jpeg "[MLTD]聖誕幼女中谷育降臨到我家")
10
[Mygo] 迷星叫 邦邦cover![[Mygo] 迷星叫 邦邦cover](https://img.youtube.com/vi/CNtXOEplNk0/mqdefault.jpg "[Mygo] 迷星叫 邦邦cover")
9
Re: [閒聊] 巫術 辟邪除妖VA 新傳說冒險者![Re: [閒聊] 巫術 辟邪除妖VA 新傳說冒險者](https://i.imgur.com/QxkcqzLb.jpeg "Re: [閒聊] 巫術 辟邪除妖VA 新傳說冒險者")
9
[閒聊] 聖誕老公公巴雷特9
[閒聊] 白雪公主 歌舞片段 “Waiting On A Wish![[閒聊] 白雪公主 歌舞片段 “Waiting On A Wish](https://img.youtube.com/vi/dZk76vGBsv8/mqdefault.jpg "[閒聊] 白雪公主 歌舞片段 “Waiting On A Wish")
20
[閒聊] 最近p站發生的留言攻擊事件