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

[pride829 (竹鼠)]

以下是根據本魯碼農自己的經驗，絕大部份參考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
→ nh60211as: 首先算錢用浮點
推 strlen: 反對者很多 而且還很大一部份是不學無術的老屁股冗員
→ strlen: 因為寫clean code很麻煩 很燒腦 很吃力不討好 懶啦
推 arrenwu: 原來寫在 function 前的comment還有特別稱呼啊XD
噓 Ratucao: 西洽點在哪
推 enmeitiryous: 所以是建議用大寫區隔函式內的詞而不是底線嗎
→ pride829: 我知道算錢有更好的方式，但我不想加入太多東西讓這篇
→ pride829: 文章對新手來說更難懂
推 Tokukenis: 推文件導向
→ eva05s: 回文不用點
→ arrenwu: 回文不是不用點 而是沒有洽點的話要跟引文有關係
→ pride829: 命名風格通常是根據程式語言跟你的團隊來做決定，以這
→ pride829: 篇文來說是Java
→ arrenwu: 這篇顯然是跟引文有關的
推 qwer338859: 回文又不用點 鬼叫什麼
推 Richun: 前面的那個不完全是comment，有的說法是doc string。
→ Richun: 像是Python有"""開頭"""結尾可以寫整串的東西能用。
推 kaj1983: 總之好懂的寫法就是對的，想辦法寫出好懂的程式也是對的
→ arrenwu: 我一直以為這些都叫做 comment XDDD
→ kuninaka: 這篇是正確的，可以自我註釋的程式碼才好讀
→ Richun: Rust有///開頭的東西，編譯同時可以輸出成文件。
推 sunshinecan: 推這篇
→ kuninaka: 我現在常常只寫註解就讓GenAI跑程式出來
→ Richun: 如果函數切分得好，函數名稱本身就是一個好的註解了。
推 h0103661: 算錢也不能用浮點，用decimal才能避免小數點問題
→ spfy: 很多語言甚至不同TEAM的規範都不同吧 這我倒是覺得統一就好
→ kuninaka: 大寫區隔函式內的詞??
→ kuninaka: 你是想說 camel case ??
→ qwer338859: 每個語言基本代碼風格規範不同這看起來是C#
→ kuninaka: 這是JAVA阿
推 arrenwu: C/C++ 是不是也是這個樣子啊？
→ qwer338859: 真的欸 那他在說什麼大寫
→ Richun: C#的命名風格是函數PascalCase，區域變數才用camelCase。
→ arrenwu: 這個變數命名那個自己組裡面講好就好了 然後寫的時候看
→ arrenwu: 一下有沒有跟旁邊的code長得太不一樣XDDD
→ Richun: 推文應該只是不知道code style，那個各語言習慣差很多。
推 kuninaka: 反正不要用奇怪的縮寫或沒意義的詞就好
→ kuninaka: 有看過初學者用ABCDEFG來命名XD
→ Richun: editorconfig解決縮排問題，coding style各語言各有工具。
→ kuninaka: 現在寫程式比以前好太多了，AI太強
→ Richun: 聽說打競賽的為了拚那幾秒，會用abc跟ijk這種免洗命名法XD
推 D122: 變數名不要取太差就還好 真的
→ spfy: https://i.imgur.com/QdO4bqq.png
→ spfy: 有些26會用漢語拼音+縮寫=通靈命名法
→ h0103661: y1s1 對岸應該很習慣
推 shadow0326: 我一直想知道中國工程師寫int64會不會過不了審
→ k960608: 不會 小學生看不懂
推 kuninaka: 26那邊真的很多拼音縮寫的智障命名法= =
→ pride829: 變數如何命名也是個大坑，一般來說你的視野（scope）越
→ pride829: 大，名稱就要越長，反之則最短
→ kuninaka: scope很大，名稱很短會死人阿XDDD
→ greatloser: 5樓菜雞還特別大聲
推 arrenwu: 所以一般會用namespace保護啊
推 Richun: 但C沒有namespace，不是在.c能用static藏的函數得很臭長。
推 arrenwu: 沒有 namespace ... 好ㄅ
→ spfy: 原來如此
推 XFarter: 其實大家指的「必須要存在的」 comment 就是原 Po 的 doc
→ XFarter: ument 吧
→ XFarter: 只是好像不是每個人都會這樣稱呼它，甚至我也只在 clean
→ XFarter: code 以及一些軟工討論才有機會看到這樣的稱呼
→ XFarter: C 因為沒有 namespace 所以 scope 更顯得重要就是了。幸
→ XFarter: 好還是有 struct 這種基本的能用
→ spfy: VS有內建的註解系統能搭配PLUGIN輸出成程式說明文件
→ spfy: 但認真寫會變成CODE以外一大堆又臭又長的XML註解 所以官方
→ spfy: 又建議你用另一個特殊的XML NODE把整份XML註解移動到一個獨
→ spfy: 立的XML檔案 然後程式碼只要指過去就好 但不知道有多少人真
→ spfy: 的有用這套XML註解功能產整份文件...
推 AnyonRedira: 推 clean code
推 wulouise: 對，你全部都重寫當然沒問題
推 silveryiris: 推
推 fman: 我自己經驗，一個禮拜這隻code就不認識了，有過看code覺得這
→ fman: 個人寫的不錯，想法和我差不多，再看作者，靠北，不就是我自
→ fman: 己，還上禮拜寫的 XD  忙的時候特別容易發生這種事情
推 lylu: 現代螢幕都夠大了取名長一點沒什麼問題 取很簡短又重複的在
→ lylu: 大型專案裡面搜關鍵字會很火
推 Galbygene: 推
推 n0029480300: 同意這篇
推 ptt0211: 算錢用浮點 遲早被人扁
推 tacodrem: 同意文件的優先重要性
→ tacodrem: 但如果遇到寫文件就像要他命的團隊...
→ tacodrem: 摸摸鼻子寫好ITS備註跟註解存證據比較快= =
→ CP64: c 姑且算是有 ns 啦 只是人家的 ns 是劃在 compile unit 上
推 melancholy07: 推
→ melancholy07: 推
→ CP64: 所以會有那種同一個元件有兩個 header 一個內用一個外帶
→ shallreturn: clean code 明明就蠻簡單的 講白了用代碼講清楚自己
→ shallreturn: 的代碼在幹嘛
推 chrisjeremy: 文件跟註解有一樣的問題 程式碼改了 功能有變化 文件
→ chrisjeremy: 不見得會更新 是說連註解都沒改了 文件更不會改
→ chrisjeremy: 但是寫文件跟維護文件很重要我舉雙手同意
→ chrisjeremy: 只是時程上往往沒有足夠的時間去維護文件
推 MK47: 推這篇 沒有code review已經夠怪了 連規範都沒有 不知道那種
→ MK47: 公司在幹嘛
推 choosin: 基本上文件先行 就沒有維護來不及的問題 再來就是如這篇
→ choosin: 所講 別誤用註解