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

[shps951015 (ITWeiHan)]

想額外小小分享個人覺得重要的概念 『 假如寫了註解一定要維護 』

舉例
前幾年老闆委託寫尾牙發錢活動程式
中間改了幾次關於金錢的邏輯，特別獎金加碼，都沒有修改過註解
今年老闆又要舉辦一次尾牙抽獎，這次沒有加碼，另外把程式交給一個新進員工來修改。

```
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
推 Fkym08: 我會騙你嗎 我說到做到
→ CaptainTeemo: 因為沒寫 unit test 呀
→ testPtt: git就是用來抓戰犯的
推 qwe85158: 記得哦
※ 編輯: shps951015 (43.229.116.218), 12/27/2018 19:33:04
→ shps951015: 同意C大，有寫單元測試就是一種保障
推 mozume: 我喜歡這句「註解會騙你，但程式碼不會騙你」
→ mozume: 遇過的太多次註解跟code完全不合的,年代越久遠的越多
→ MOONY135: 讓我們感謝那位工程師的犧牲奉獻
→ robler: 註解很多時候是在補充說明 讓你可以不用把程式看完
→ robler: 你要知道，很多程式光是看完，追蹤一次就要花一整天
→ robler: 然後方法的名子又不能寫太長 註解就很有用了
→ robler: 程式碼雖然不會騙你，但是要寫的讓別人看不懂卻很容易
推 yyc1217: 倒是覺得把1和2000寫進註解 就是magic number的問題
→ yyc1217: 這兩個應該是傳進去的參數才對
→ yyc1217: 註解應該寫成「超過年限就給獎金」
→ yyc1217: @param int 年限 / @param int 獎金
推 s06yji3: 註解應該避免寫邏輯和magic number
→ shps951015: 同意y大跟S大想法
推 googoo1102: 應該有個calBonus帶入員工資料 然後回傳獎金
推 googoo1102: 2000金額寫在db或是檔案裡
推 Jichang: 這程式本身就寫的不好了 8000不會寫在哪裡
→ lazarus1121: 大方向的註解還是必要的   不用那麼細
→ shps951015: X大，是的正常不會這樣搞的，恩...我在想想舉例好了
→ lazarus1121: 至少要讓人知道這段程式的主要目的是啥
→ shps951015: 我想想有沒有簡單不複雜的例子，可以表達我想要的
→ lazarus1121: 我看過map包map總共包了4層的程式   沒有註解
→ lazarus1121: 我浪費半天時間讀他  最後直接打掉變MultiKeyMap
→ shps951015: 之前寫Java有看過這樣的例子 但例子是LinkHashMap
→ shps951015: 想到之前有看過在註解解釋HashMap原理的....
推 hellomotogg: 實作邏輯改了 method名稱沒改 被騙QQ
→ xxtuoo: 類似的..老實寫註解跟屬名..後面人改code不改註解..更後面
→ xxtuoo: 人怪我 註解亂寫誤導...以後一律只剩source..Zzz
→ xxtuoo:                     署名
推 ppc: XDDDDDD
→ ppc: 註解解釋HashMap原理也太逗
→ rofellosx: 不用先測試嗎?
推 DCTmaybe: 問一下：所以多發的獎金有拿到手嗎？
→ shps951015: 大大，抱歉讓你誤會了，這只是舉例，實際沒有發生過的
→ MOONY135: 應該是會給 不然太沒有面子
→ b81314: 這當然是舉例拉- -
推 DCTmaybe: 抱歉沒看到舉例XDD
推 hankyan919: 這就是code review 的重要性 改功能reviewer也要看註
→ hankyan919: 解
推 skizard: 註解不需要寫到這麼細阿 讓人快速帶入邏輯就好
→ Ekmund: 這case推到線上去問題不在註解吧 在驗證
→ Ekmund: 真正傷害的是RD的時間成本 所以思考面向要變成
→ Ekmund: 規範註解該寫些什麼 使用的地方和內容
→ Ekmund: 比方說 只寫功能 不詳述規則 而是寫“根據年資發獎金”
→ Ekmund: 但是把實際數據留在版編資訊 也好追查變化
→ Ekmund: 或是交給外部輸入 讓老闆自己邊看邊調
推 ggttoo: 推樓上的方法不錯
→ descent: 有句話說, 註解和程式碼可能都是錯的
噓 darkMood: 胡址，註解的功能不是其他方式可以取代，而這裡的問題
→ darkMood: 是沒有做測試，這樣改程式本來就該處死，關註解屁事
→ darkMood: 更別說註解又不是這樣亂寫一通就可以了，少污化名註解
→ TAKADO: 這種註解還不如不寫，而且目的/邏輯應該寫在文件裡吧