作者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/cn.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