作者ripple0129 (perry tsai)
看板Soft_Job
标题Re: [讨论] 要不要写注解
时间Fri Oct 25 22:40:08 2019
这个问题讨论很多次了
先讲一下写注解最可能的缺点好了
第一 程式码与注解不同步
也就是当程式码更新的时候
注解没有更新
第二 多了许多杂讯
如果注解没写好的话
反而是个干扰阅读的东西
那不写注解又有什麽缺点
第一 对於功能没有说明都需要由程式码来了解
所以可能必须花更长的时间来理解
第二 特例的状况绝对会感到莫名奇妙
譬如老板说王董的帐号给他特权
莫名奇妙就多个if user xxx then xxx
抓不着头绪
所以该不该写注解就是看当下场景做选择了
程式码能够表达明确的意图
也就是程式码本身就能够提供良好的说明
那当然可以不用写
如果逻辑十分复杂
程式码很难表达意图
那该写的还是要写
再来就是特例几乎都要写
写了程式码回过头看自己程式码
摸摸良心认为别人不需要注解也能看的懂的话
那就不用写了
如果自己不能判断别人有没有办法看懂
那还是乖乖补上别害人了
※ 引述《sec5566 (sec)》之铭言：
: 听过说法是
: 1.写注解是浪费时间，命名命的好不需要写
: 2.写注解方便维护，而且读中文一定比读英文快
: 自己是常常忽略注解，
: 不过有空还是会补上，
: 因为程式都只有我在弄，
: 但是当大型系统过一阵子在拿出来改时，
: 就知道不写注解真的是省小时间花大时间，
: 像是一堆函式传几个变数能跑出什麽，
: 还是同样提资料，这2个提出来差在哪？
: 不写後面维护的人，就要很辛苦去看里面，
: 尤其是交接工作，
: 大家会写注解吗？
: -----
: Sent from JPTT on my Sony H4331.
--
※ 发信站: 批踢踢实业坊(ptt.cc), 来自: 101.9.226.207 (台湾)
※ 文章网址: https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1572014410.A.A3C.html
1F：→ viper9709: 推 10/25 23:32
2F：推 Ghamu: 逻辑十分复杂想写注解的时候通常代表着该重构了 10/26 11:11
3F：→ Ghamu: 注解不该描述程式码本身 应该描述程式码里面没有提到的事情 10/26 11:14
4F：→ Ghamu: 类似写这段的意图 举例类似有一个奇怪的写法是要避掉一个b 10/26 11:14
5F：→ Ghamu: ug这就该特别描述 10/26 11:14
6F：→ Ghamu: 注解应该要写的是你单看程式码看不到的东西 要帮助程式码本 10/26 11:15
7F：→ Ghamu: 身可理解就靠命名跟拆分 10/26 11:15
8F：推 michael0728n: 同意楼上，看到注解写这是为了绕开奇怪的opensource 10/26 11:49
9F：→ michael0728n: bug还附讨论连结真的会感动到痛苦流涕XD 10/26 11:49
10F：推 Ghamu: 我只是照抄Clean code而已 欢迎大家买回家看(打书XD 10/26 12:25
11F：→ joejoe14758: 问题是通常都没有人有时间重构啦 10/26 17:52
12F：→ testPtt: 因为刚开始写通常不会去想abstract virtual interface 10/26 19:30
13F：→ testPtt: 这些东西 所以重构也就觉得很乱 10/26 19:31
14F：推 hankyan919: 坦白说注解要改写比变数名称改写方便多了 10/26 23:44