顯示廣告
隱藏 ✕
※ 本文為 terievv 轉寄自 ptt.cc 更新時間: 2018-12-29 23:22:30
看板 Soft_Job
作者 Ghamu (貓丸)
標題
 Re: [請益] 寫註解到底是不是好習慣

時間 Sat Dec 29 04:36:59 2018


個人淺見

註解是可恥的

代表你程式不夠乾淨

變數 函式名稱詞不達意 只能靠註解補完

最近手上接到外包的程式碼

有一個核心處理封包差不多200行程式碼

裡面做什麼呢?

他有好心寫上註解

//處理messages類型 A
.
.
.
//處理類型B
.
.
.
//..............C

欸.....

那實際上不就該是

處理類型A();

處理類型B();

處理類型C();

嗎???

當註解變多時 或開始寫註解時

就是一個該refactoring的信號了

當然說可恥是有點偏激

主重點在於說應該盡力窮盡所能

讓程式碼即註解

而不是去依賴註解


註解雖然可恥 但是有用

在以下情形我還是會註解

1.英文不夠好

有時候想不到該怎麼描述才清楚

畢竟不是英文母語

只好寫上註解 等未來有緣人幫忙修改

2.變數名稱 函式因為單字太長

冷僻縮寫 我會加上註解 別讓下一個人猜

3. 非正規解法 詭異做法時

最近剛好遇到Java rename 會失敗的問題

一位資深的前輩說是因為裡面一連串動作

有一個錯他就整個錯

建議把他拆開來做 先複製 改名 move 等等

如果自己寫一個rename ()

把這些步驟放進去

下一個人看到

一定會疑惑為什麼要自己重寫吧?

這時候就要加上註解描述是因為有那個風險

才做此改變


簡單的說

程式碼就是註解

註解不要重複描述程式碼

註解要能提供程式碼以外 你的設計意圖


-----
Sent from JPTT on my Sony F5321.

--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 114.25.229.193
※ 文章代碼(AID): #1S9ebjDU (Soft_Job)
※ 文章網址: https://www.ptt.cc/bbs/Soft_Job/M.1546029421.A.35E.html
orange0319: 認同1F 12/29 09:09
Ryuusei: 推一個,我也是只有在程式碼本身不足以表達全部資訊的時2F 12/29 09:18
Ryuusei: 候才寫註解
Angesi: 等你要離職時  你會後悔寫了註解...4F 12/29 10:09
cookie1115: 推5F 12/29 13:01
darkMood: 笑死,你到底知不知道什麼時候該寫註解?6F 12/29 21:50
darkMood: 註解的價值和你的廢文無關,不會寫註解不要牽拖註解不好

--
※ 看板: terievv 文章推薦值: 0 目前人氣: 0 累積人氣: 78 
r)回覆 e)編輯 d)刪除 M)不收藏 ^x)轉錄 同主題: =)首篇 [)上篇 ])下篇