作者shps951015 (ITWeiHan)
看板Soft_Job
标题Re: [请益] 写注解到底是不是好习惯
时间Thu Dec 27 18:34:53 2018
想额外小小分享个人觉得重要的概念 『 假如写了注解一定要维护 』
举例
前几年老板委托写尾牙发钱活动程式
中间改了几次关於金钱的逻辑，特别奖金加码，都没有修改过注解
今年老板又要举办一次尾牙抽奖，这次没有加码，另外把程式交给一个新进员工来修改。
```
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://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1545906896.A.B55.html
1F：推 Fkym08: 我会骗你吗 我说到做到 12/27 18:49
2F：→ CaptainTeemo: 因为没写 unit test 呀 12/27 18:57
3F：→ testPtt: git就是用来抓战犯的 12/27 19:09
4F：推 qwe85158: 记得哦 12/27 19:21
※ 编辑: shps951015 (43.229.116.218), 12/27/2018 19:33:04
5F：→ shps951015: 同意C大，有写单元测试就是一种保障 12/27 19:34
6F：推 mozume: 我喜欢这句「注解会骗你，但程式码不会骗你」 12/27 19:44
7F：→ mozume: 遇过的太多次注解跟code完全不合的,年代越久远的越多 12/27 19:45
8F：→ MOONY135: 让我们感谢那位工程师的牺牲奉献 12/27 20:13
9F：→ robler: 注解很多时候是在补充说明 让你可以不用把程式看完 12/27 21:00
10F：→ robler: 你要知道，很多程式光是看完，追踪一次就要花一整天 12/27 21:01
11F：→ robler: 然後方法的名子又不能写太长 注解就很有用了 12/27 21:01
12F：→ robler: 程式码虽然不会骗你，但是要写的让别人看不懂却很容易 12/27 21:02
13F：推 yyc1217: 倒是觉得把1和2000写进注解 就是magic number的问题 12/27 21:03
14F：→ yyc1217: 这两个应该是传进去的参数才对 12/27 21:03
15F：→ yyc1217: 注解应该写成「超过年限就给奖金」 12/27 21:06
16F：→ yyc1217: @param int 年限 / @param int 奖金 12/27 21:06
17F：推 s06yji3: 注解应该避免写逻辑和magic number 12/27 21:08
18F：→ shps951015: 同意y大跟S大想法 12/27 21:19
19F：推 googoo1102: 应该有个calBonus带入员工资料 然後回传奖金 12/27 21:36
20F：推 googoo1102: 2000金额写在db或是档案里 12/27 21:41
21F：推 Jichang: 这程式本身就写的不好了 8000不会写在哪里 12/27 21:47
22F：→ lazarus1121: 大方向的注解还是必要的 不用那麽细 12/27 21:59
23F：→ shps951015: X大，是的正常不会这样搞的，恩...我在想想举例好了 12/27 21:59
24F：→ lazarus1121: 至少要让人知道这段程式的主要目的是啥 12/27 22:00
25F：→ shps951015: 我想想有没有简单不复杂的例子，可以表达我想要的 12/27 22:01
26F：→ lazarus1121: 我看过map包map总共包了4层的程式 没有注解 12/27 22:01
27F：→ lazarus1121: 我浪费半天时间读他 最後直接打掉变MultiKeyMap 12/27 22:03
28F：→ shps951015: 之前写Java有看过这样的例子 但例子是LinkHashMap 12/27 22:08
29F：→ shps951015: 想到之前有看过在注解解释HashMap原理的.... 12/27 22:10
30F：推 hellomotogg: 实作逻辑改了 method名称没改 被骗QQ 12/27 23:00
31F：→ xxtuoo: 类似的..老实写注解跟属名..後面人改code不改注解..更後面 12/27 23:38
32F：→ xxtuoo: 人怪我 注解乱写误导...以後一律只剩source..Zzz 12/27 23:38
33F：→ xxtuoo: 署名 12/27 23:39
34F：推 ppc: XDDDDDD 12/28 02:19
35F：→ ppc: 注解解释HashMap原理也太逗 12/28 02:20
36F：→ rofellosx: 不用先测试吗? 12/28 09:33
37F：推 DCTmaybe: 问一下：所以多发的奖金有拿到手吗？ 12/28 10:44
38F：→ shps951015: 大大，抱歉让你误会了，这只是举例，实际没有发生过的 12/28 11:30
39F：→ MOONY135: 应该是会给 不然太没有面子 12/28 11:30
40F：→ b81314: 这当然是举例拉- - 12/28 13:12
41F：推 DCTmaybe: 抱歉没看到举例XDD 12/28 13:23
42F：推 hankyan919: 这就是code review 的重要性 改功能reviewer也要看注 12/28 13:24
43F：→ hankyan919: 解 12/28 13:24
44F：推 skizard: 注解不需要写到这麽细阿 让人快速带入逻辑就好 12/28 14:34
45F：→ Ekmund: 这case推到线上去问题不在注解吧 在验证 12/28 14:50
46F：→ Ekmund: 真正伤害的是RD的时间成本 所以思考面向要变成 12/28 14:51
47F：→ Ekmund: 规范注解该写些什麽 使用的地方和内容 12/28 14:51
48F：→ Ekmund: 比方说 只写功能 不详述规则 而是写“根据年资发奖金” 12/28 14:52
49F：→ Ekmund: 但是把实际数据留在版编资讯 也好追查变化 12/28 14:53
50F：→ Ekmund: 或是交给外部输入 让老板自己边看边调 12/28 14:55
51F：推 ggttoo: 推楼上的方法不错 12/28 18:38
52F：→ descent: 有句话说, 注解和程式码可能都是错的 12/28 22:01
53F：嘘 darkMood: 胡址，注解的功能不是其他方式可以取代，而这里的问题 12/29 01:46
54F：→ darkMood: 是没有做测试，这样改程式本来就该处死，关注解屁事 12/29 01:46
55F：→ darkMood: 更别说注解又不是这样乱写一通就可以了，少污化名注解 12/29 01:46
56F：→ TAKADO: 这种注解还不如不写，而且目的/逻辑应该写在文件里吧 12/29 17:19