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

看板Soft_Job作者 (ITWeiHan)時間5年前 (2018/12/27 18:34), 5年前編輯推噓14(15推 1噓 40→)
留言56則, 26人參與, 5年前最新討論串3/24 (看更多)
想額外小小分享個人覺得重要的概念 『 假如寫了註解一定要維護 』 舉例 前幾年老闆委託寫尾牙發錢活動程式 中間改了幾次關於金錢的邏輯，特別獎金加碼，都沒有修改過註解 今年老闆又要舉辦一次尾牙抽獎，這次沒有加碼，另外把程式交給一個新進員工來修改。 ``` void Main(){ /* 邏輯: ..略 - 當年資超過一年，獎金+2000 ..略 */ newYearBonusService.SetBonus(emloyee) } class NewYearBonusService{ public void SetBonus(Employee emloyee){ ..略 if(GetJobTenure(emloyee)>=1) emloyee.Bonus += 8000; ..略 } } ``` 結果新人沒有去花時間去讀程式，直接相信你的註解，直接上線 抽獎當天才發現錢多給了6000，老闆大怒。 類似概念的例子在在現實偶而遇到，因為需求常變更，貪一時之便不去維護註解， 反而一開始就不要註解，把變數、方法命名取好，模組化做好，反而有更有幫助。 另外讀別人註解我個人的觀念(對版上很多前輩應該是基本概念): 『 註解只是補助，程式才是本體 註解會騙你，但程式碼不會騙你 』 -- ※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 43.229.116.218 ※ 文章網址: https://www.ptt.cc/bbs/Soft_Job/M.1545906896.A.B55.html
推
12/27 18:49, 5年前 , 1F
我會騙你嗎 我說到做到
12/27 18:49, 1F
→
12/27 18:57, 5年前 , 2F
因為沒寫 unit test 呀
12/27 18:57, 2F
→
12/27 19:09, 5年前 , 3F
git就是用來抓戰犯的
12/27 19:09, 3F
推
12/27 19:21, 5年前 , 4F
記得哦
12/27 19:21, 4F
※ 編輯: shps951015 (43.229.116.218), 12/27/2018 19:33:04
→
12/27 19:34, 5年前 , 5F
同意C大，有寫單元測試就是一種保障
12/27 19:34, 5F
推
12/27 19:44, 5年前 , 6F
我喜歡這句「註解會騙你，但程式碼不會騙你」
12/27 19:44, 6F
→
12/27 19:45, 5年前 , 7F
遇過的太多次註解跟code完全不合的,年代越久遠的越多
12/27 19:45, 7F
→
12/27 20:13, 5年前 , 8F
讓我們感謝那位工程師的犧牲奉獻
12/27 20:13, 8F
→
12/27 21:00, 5年前 , 9F
註解很多時候是在補充說明 讓你可以不用把程式看完
12/27 21:00, 9F
→
12/27 21:01, 5年前 , 10F
你要知道，很多程式光是看完，追蹤一次就要花一整天
12/27 21:01, 10F
→
12/27 21:01, 5年前 , 11F
然後方法的名子又不能寫太長 註解就很有用了
12/27 21:01, 11F
→
12/27 21:02, 5年前 , 12F
程式碼雖然不會騙你，但是要寫的讓別人看不懂卻很容易
12/27 21:02, 12F
推
12/27 21:03, 5年前 , 13F
倒是覺得把1和2000寫進註解 就是magic number的問題
12/27 21:03, 13F
→
12/27 21:03, 5年前 , 14F
這兩個應該是傳進去的參數才對
12/27 21:03, 14F
→
12/27 21:06, 5年前 , 15F
註解應該寫成「超過年限就給獎金」
12/27 21:06, 15F
→
12/27 21:06, 5年前 , 16F
@param int 年限 / @param int 獎金
12/27 21:06, 16F
推
12/27 21:08, 5年前 , 17F
註解應該避免寫邏輯和magic number
12/27 21:08, 17F
→
12/27 21:19, 5年前 , 18F
同意y大跟S大想法
12/27 21:19, 18F
推
12/27 21:36, 5年前 , 19F
應該有個calBonus帶入員工資料 然後回傳獎金
12/27 21:36, 19F
推
12/27 21:41, 5年前 , 20F
2000金額寫在db或是檔案裡
12/27 21:41, 20F
推
12/27 21:47, 5年前 , 21F
這程式本身就寫的不好了 8000不會寫在哪裡
12/27 21:47, 21F
→
12/27 21:59, 5年前 , 22F
大方向的註解還是必要的 不用那麼細
12/27 21:59, 22F
→
12/27 21:59, 5年前 , 23F
X大，是的正常不會這樣搞的，恩...我在想想舉例好了
12/27 21:59, 23F
→
12/27 22:00, 5年前 , 24F
至少要讓人知道這段程式的主要目的是啥
12/27 22:00, 24F
→
12/27 22:01, 5年前 , 25F
我想想有沒有簡單不複雜的例子，可以表達我想要的
12/27 22:01, 25F
→
12/27 22:01, 5年前 , 26F
我看過map包map總共包了4層的程式 沒有註解
12/27 22:01, 26F
→
12/27 22:03, 5年前 , 27F
我浪費半天時間讀他 最後直接打掉變MultiKeyMap
12/27 22:03, 27F
→
12/27 22:08, 5年前 , 28F
之前寫Java有看過這樣的例子 但例子是LinkHashMap
12/27 22:08, 28F
→
12/27 22:10, 5年前 , 29F
想到之前有看過在註解解釋HashMap原理的....
12/27 22:10, 29F
推
12/27 23:00, 5年前 , 30F
實作邏輯改了 method名稱沒改 被騙QQ
12/27 23:00, 30F
→
12/27 23:38, 5年前 , 31F
類似的..老實寫註解跟屬名..後面人改code不改註解..更後面
12/27 23:38, 31F
→
12/27 23:38, 5年前 , 32F
人怪我 註解亂寫誤導...以後一律只剩source..Zzz
12/27 23:38, 32F
→
12/27 23:39, 5年前 , 33F
署名
12/27 23:39, 33F
推
12/28 02:19, 5年前 , 34F
XDDDDDD
12/28 02:19, 34F
→
12/28 02:20, 5年前 , 35F
註解解釋HashMap原理也太逗
12/28 02:20, 35F
→
12/28 09:33, 5年前 , 36F
不用先測試嗎?
12/28 09:33, 36F
推
12/28 10:44, 5年前 , 37F
問一下：所以多發的獎金有拿到手嗎？
12/28 10:44, 37F
→
12/28 11:30, 5年前 , 38F
大大，抱歉讓你誤會了，這只是舉例，實際沒有發生過的
12/28 11:30, 38F
→
12/28 11:30, 5年前 , 39F
應該是會給 不然太沒有面子
12/28 11:30, 39F
→
12/28 13:12, 5年前 , 40F
這當然是舉例拉- -
12/28 13:12, 40F
推
12/28 13:23, 5年前 , 41F
抱歉沒看到舉例XDD
12/28 13:23, 41F
推
12/28 13:24, 5年前 , 42F
這就是code review 的重要性 改功能reviewer也要看註
12/28 13:24, 42F
→
12/28 13:24, 5年前 , 43F
解
12/28 13:24, 43F
推
12/28 14:34, 5年前 , 44F
註解不需要寫到這麼細阿 讓人快速帶入邏輯就好
12/28 14:34, 44F
→
12/28 14:50, 5年前 , 45F
這case推到線上去問題不在註解吧 在驗證
12/28 14:50, 45F
→
12/28 14:51, 5年前 , 46F
真正傷害的是RD的時間成本 所以思考面向要變成
12/28 14:51, 46F
→
12/28 14:51, 5年前 , 47F
規範註解該寫些什麼 使用的地方和內容
12/28 14:51, 47F
→
12/28 14:52, 5年前 , 48F
比方說 只寫功能 不詳述規則 而是寫“根據年資發獎金”
12/28 14:52, 48F
→
12/28 14:53, 5年前 , 49F
但是把實際數據留在版編資訊 也好追查變化
12/28 14:53, 49F
→
12/28 14:55, 5年前 , 50F
或是交給外部輸入 讓老闆自己邊看邊調
12/28 14:55, 50F
推
12/28 18:38, 5年前 , 51F
推樓上的方法不錯
12/28 18:38, 51F
→
12/28 22:01, 5年前 , 52F
有句話說, 註解和程式碼可能都是錯的
12/28 22:01, 52F
噓
12/29 01:46, 5年前 , 53F
胡址，註解的功能不是其他方式可以取代，而這裡的問題
12/29 01:46, 53F
→
12/29 01:46, 5年前 , 54F
是沒有做測試，這樣改程式本來就該處死，關註解屁事
12/29 01:46, 54F
→
12/29 01:46, 5年前 , 55F
更別說註解又不是這樣亂寫一通就可以了，少污化名註解
12/29 01:46, 55F
→
12/29 17:19, 5年前 , 56F
這種註解還不如不寫，而且目的/邏輯應該寫在文件裡吧
12/29 17:19, 56F
‣ 更多 shps951015 的文章
文章代碼(AID): #1S9AhGjL (Soft_Job)
討論串 (同標題文章)
完整討論串 (本文為第 3 之 24 篇)：
排序： 最舊先 | 最新先 | 留言數
在新視窗開啟完整討論串 (共24篇)
‣ 更多 shps951015 的文章
文章代碼(AID): #1S9AhGjL (Soft_Job)