作者SHANGOYANYI (彥一)
看板Soft_Job
標題Re: [討論] 要不要寫註解
時間Sat Oct 26 19:35:07 2019
寫啊 當然要寫
但是不是拿來把程式邏輯用中文或英文重寫一次
而是要把這段程式的緣由、目的、特例交代清楚
比如
// 此功能因某某某要求故加上XXX 2019.10.26
如果能把ticket單號列進來更好
這樣一看這段註解就能了解當時作業的來龍去脈
以後老闆靠邀為什麼要寫xxx功能時
才能冤有頭債有主 搞不好就他媽老闆當初自己開的ticket
所以說 好註解不寫嗎？
※ 引述《ripple0129 (perry tsai)》之銘言：
: 這個問題討論很多次了
: 先講一下寫註解最可能的缺點好了
: 第一 程式碼與註解不同步
: 也就是當程式碼更新的時候
: 註解沒有更新
: 第二 多了許多雜訊
: 如果註解沒寫好的話
: 反而是個干擾閱讀的東西
: 那不寫註解又有什麼缺點
: 第一 對於功能沒有說明都需要由程式碼來了解
: 所以可能必須花更長的時間來理解
: 第二 特例的狀況絕對會感到莫名奇妙
: 譬如老闆說王董的帳號給他特權
: 莫名奇妙就多個if user xxx then xxx
: 抓不著頭緒
: 所以該不該寫註解就是看當下場景做選擇了
: 程式碼能夠表達明確的意圖
: 也就是程式碼本身就能夠提供良好的說明
: 那當然可以不用寫
: 如果邏輯十分複雜
: 程式碼很難表達意圖
: 那該寫的還是要寫
: 再來就是特例幾乎都要寫
: 寫了程式碼回過頭看自己程式碼
: 摸摸良心認為別人不需要註解也能看的懂的話
: 那就不用寫了
: 如果自己不能判斷別人有沒有辦法看懂
: 那還是乖乖補上別害人了
: ※ 引述《sec5566 (sec)》之銘言：
: : 聽過說法是
: : 1.寫註解是浪費時間，命名命的好不需要寫
: : 2.寫註解方便維護，而且讀中文一定比讀英文快
: : 自己是常常忽略註解，
: : 不過有空還是會補上，
: : 因為程式都只有我在弄，
: : 但是當大型系統過一陣子在拿出來改時，
: : 就知道不寫註解真的是省小時間花大時間，
: : 像是一堆函式傳幾個變數能跑出什麼，
: : 還是同樣提資料，這2個提出來差在哪？
: : 不寫後面維護的人，就要很辛苦去看裡面，
: : 尤其是交接工作，
: : 大家會寫註解嗎？
: : -----
: : Sent from JPTT on my Sony H4331.
--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 223.140.228.68 (臺灣)
※ 文章網址: https://webptt.com/m.aspx?n=bbs/Soft_Job/M.1572089709.A.B50.html
1F：→ wvwvwvwvwv: commit message:Am i a joke to you ? 10/26 19:38
2F：→ SimonAllen: Gitlens: 10/26 19:38
3F：推 thsyou9527: 我也會這樣寫 誰提的要求 就註記誰＋日期＋單號 10/26 19:44
4F：推 geroge0820: 一樓WWW 寫在commit message抓戰犯也容易 10/26 20:05
5F：推 michaelchen1: 以前自從被主管狗幹後就會寫了 明明是他叫我改欄位 10/26 20:05
6F：→ michaelchen1: 2個月後就被抓來狗幹為什麼要亂改..... 10/26 20:06
7F：→ michaelchen1: 剛畢業還不懂後來同事就教我要這樣寫XD 10/26 20:06
8F：推 yamakazi: 這些東西可以寫在issue tracker上就好吧 還有像Perforce 10/26 20:13
9F：→ yamakazi: 有time lapse view 哪段code是哪天commit上去的 單號多 10/26 20:13
10F：→ yamakazi: 少ㄧ目了然 10/26 20:13
11F：→ yamakazi: 誰提需求通常就誰提單 進扣後coomet寫上單號就好 有用ji 10/26 20:15
12F：→ yamakazi: ra+fisheye的話會幫你自動連好review 10/26 20:15
13F：→ yamakazi: 還有像是解完bug的root cause和solution也是寫在issue t 10/26 20:17
14F：→ yamakazi: racker 而不是寫在code內註解 10/26 20:17
15F：推 knives: 樓上那樣比較好 10/26 20:24
16F：推 ymcheung: 有一次 gitlens 在一行空白顯示「聽見天上的聲音了」 10/26 20:26
17F：→ ymcheung: 嚇到整個醒過來，麻煩不要留這種怪東西... 10/26 20:26
18F：推 vi000246: 直接git blame就好了 10/26 20:44
19F：→ windlll: git commit：如9/16一樣，增加parser fun.，然後我就被 10/26 21:21
20F：→ windlll: 嚇醒了 10/26 21:21
21F：→ popcool: 有一種東西叫做commit msg 10/27 00:24
22F：推 chienweichih: 一言不合就 blame 10/27 00:45
23F：→ saladim: p4有個缺點 當branch out出去幾次後 要向上找才能找到 10/27 01:15
24F：→ saladim: 老一點的commit msg 10/27 01:16
25F：→ Ghamu: 這種東西我是寫在commit log裡面 其實也不用寫在註解 調com 10/27 03:27
26F：→ Ghamu: mit log即可 還有diff 時間戳記 10/27 03:27