Re: [請益] 寫註解到底是不是好習慣

作者: shps951015 (寶寶QQ)   2018-12-27 18:34:53
想額外小小分享個人覺得重要的概念 『 假如寫了註解一定要維護 』
舉例
前幾年老闆委託寫尾牙發錢活動程式
中間改了幾次關於金錢的邏輯,特別獎金加碼,都沒有修改過註解
今年老闆又要舉辦一次尾牙抽獎,這次沒有加碼,另外把程式交給一個新進員工來修改。
```
void Main(){
/*
邏輯:
..略
- 當年資超過一年,獎金+2000
..略
*/
newYearBonusService.SetBonus(emloyee)
}
class NewYearBonusService{
public void SetBonus(Employee emloyee){
..略
if(GetJobTenure(emloyee)>=1) emloyee.Bonus += 8000;
..略
}
}
```
結果新人沒有去花時間去讀程式,直接相信你的註解,直接上線
抽獎當天才發現錢多給了6000,老闆大怒。
類似概念的例子在在現實偶而遇到,因為需求常變更,貪一時之便不去維護註解,
反而一開始就不要註解,把變數、方法命名取好,模組化做好,反而有更有幫助。
另外讀別人註解我個人的觀念(對版上很多前輩應該是基本概念):
『 註解只是補助,程式才是本體
註解會騙你,但程式碼不會騙你 』
作者: Fkym08 (fkym)   2018-12-27 18:49:00
我會騙你嗎 我說到做到
作者: CaptainTeemo (提摩隊長)   2018-12-27 18:57:00
因為沒寫 unit test 呀
作者: testPtt (測試)   2018-12-27 19:09:00
git就是用來抓戰犯的
作者: qwe85158 (xine)   2018-12-27 19:21:00
記得哦
作者: shps951015 (寶寶QQ)   2018-12-27 19:34:00
同意C大,有寫單元測試就是一種保障
作者: mozume (米蟲)   2018-12-27 19:44:00
我喜歡這句「註解會騙你,但程式碼不會騙你」遇過的太多次註解跟code完全不合的,年代越久遠的越多
作者: MOONY135 (談無慾)   2018-12-27 20:13:00
讓我們感謝那位工程師的犧牲奉獻
作者: robler (章魚丸)   2018-12-27 21:00:00
註解很多時候是在補充說明 讓你可以不用把程式看完你要知道,很多程式光是看完,追蹤一次就要花一整天然後方法的名子又不能寫太長 註解就很有用了程式碼雖然不會騙你,但是要寫的讓別人看不懂卻很容易
作者: yyc1217 (somo)   2018-12-27 21:03:00
倒是覺得把1和2000寫進註解 就是magic number的問題這兩個應該是傳進去的參數才對註解應該寫成「超過年限就給獎金」@param int 年限 / @param int 獎金
作者: s06yji3 (阿南)   2018-12-27 21:08:00
註解應該避免寫邏輯和magic number
作者: shps951015 (寶寶QQ)   2018-12-27 21:19:00
同意y大跟S大想法
作者: googoo1102 (googoo)   2018-12-27 21:36:00
應該有個calBonus帶入員工資料 然後回傳獎金2000金額寫在db或是檔案裡
作者: Jichang (C.C.Lemon)   2018-12-27 21:47:00
這程式本身就寫的不好了 8000不會寫在哪裡
作者: lazarus1121 (...)   2018-12-27 21:59:00
大方向的註解還是必要的 不用那麼細
作者: shps951015 (寶寶QQ)   2018-12-27 21:59:00
X大,是的正常不會這樣搞的,恩...我在想想舉例好了
作者: lazarus1121 (...)   2018-12-27 22:00:00
至少要讓人知道這段程式的主要目的是啥
作者: shps951015 (寶寶QQ)   2018-12-27 22:01:00
我想想有沒有簡單不複雜的例子,可以表達我想要的
作者: lazarus1121 (...)   2018-12-27 22:01:00
我看過map包map總共包了4層的程式 沒有註解我浪費半天時間讀他 最後直接打掉變MultiKeyMap
作者: shps951015 (寶寶QQ)   2018-12-27 22:08:00
之前寫Java有看過這樣的例子 但例子是LinkHashMap想到之前有看過在註解解釋HashMap原理的....
作者: hellomotogg (你好機車)   2018-12-27 23:00:00
實作邏輯改了 method名稱沒改 被騙QQ
作者: xxtuoo (浪費時間不好QQ)   2018-12-27 23:38:00
類似的..老實寫註解跟屬名..後面人改code不改註解..更後面人怪我 註解亂寫誤導...以後一律只剩source..Zzz署名
作者: ppc ( )   2018-12-28 02:19:00
XDDDDDD註解解釋HashMap原理也太逗
作者: rofellosx (鏖)   2018-12-28 09:33:00
不用先測試嗎?
作者: DCTmaybe (竹竹人)   2018-12-28 10:44:00
問一下:所以多發的獎金有拿到手嗎?
作者: shps951015 (寶寶QQ)   2018-12-28 11:30:00
大大,抱歉讓你誤會了,這只是舉例,實際沒有發生過的
作者: MOONY135 (談無慾)   2018-12-28 11:30:00
應該是會給 不然太沒有面子
作者: b81314 (有點貴)   2018-12-28 13:12:00
這當然是舉例拉- -
作者: DCTmaybe (竹竹人)   2018-12-28 13:23:00
抱歉沒看到舉例XDD
作者: hankyan919 (比奇堡樂隊)   2018-12-28 13:24:00
這就是code review 的重要性 改功能reviewer也要看註解
作者: skizard ( )   2018-12-28 14:34:00
註解不需要寫到這麼細阿 讓人快速帶入邏輯就好
作者: Ekmund (是一隻小叔)   2018-12-28 14:50:00
這case推到線上去問題不在註解吧 在驗證真正傷害的是RD的時間成本 所以思考面向要變成規範註解該寫些什麼 使用的地方和內容比方說 只寫功能 不詳述規則 而是寫“根據年資發獎金”但是把實際數據留在版編資訊 也好追查變化或是交給外部輸入 讓老闆自己邊看邊調
作者: ggttoo (中華隊加油!!!)   2018-12-28 18:38:00
推樓上的方法不錯
作者: descent (「雄辯是銀,沉默是金」)   2018-12-28 22:01:00
有句話說, 註解和程式碼可能都是錯的
作者: darkMood (瞬間投射)   2018-12-29 01:46:00
胡址,註解的功能不是其他方式可以取代,而這裡的問題是沒有做測試,這樣改程式本來就該處死,關註解屁事更別說註解又不是這樣亂寫一通就可以了,少污化名註解
作者: TAKADO (朕沒給的你不能搶)   2018-12-29 17:19:00
這種註解還不如不寫,而且目的/邏輯應該寫在文件裡吧

Links booklink

Contact Us: admin [ a t ] ucptt.com