Re: [请益] 写注解到底是不是好习惯

楼主: shps951015 (宝宝QQ)   2018-12-27 18:34:53
想额外小小分享个人觉得重要的概念 ‘ 假如写了注解一定要维护 ’
举例
前几年老板委托写尾牙发钱活动程式
中间改了几次关于金钱的逻辑,特别奖金加码,都没有修改过注解
今年老板又要举办一次尾牙抽奖,这次没有加码,另外把程式交给一个新进员工来修改。
```
void Main(){
/*
逻辑:
..略
- 当年资超过一年,奖金+2000
..略
*/
newYearBonusService.SetBonus(emloyee)
}
class NewYearBonusService{
public void SetBonus(Employee emloyee){
..略
if(GetJobTenure(emloyee)>=1) emloyee.Bonus += 8000;
..略
}
}
```
结果新人没有去花时间去读程式,直接相信你的注解,直接上线
抽奖当天才发现钱多给了6000,老板大怒。
类似概念的例子在在现实偶而遇到,因为需求常变更,贪一时之便不去维护注解,
反而一开始就不要注解,把变量、方法命名取好,模组化做好,反而有更有帮助。
另外读别人注解我个人的观念(对版上很多前辈应该是基本概念):
‘ 注解只是补助,程式才是本体
注解会骗你,但程式码不会骗你 ’
作者: Fkym08 (fkym)   2018-12-27 18:49:00
我会骗你吗 我说到做到
作者: CaptainTeemo (提摩队长)   2018-12-27 18:57:00
因为没写 unit test 呀
作者: testPtt (测试)   2018-12-27 19:09:00
git就是用来抓战犯的
作者: qwe85158 (xine)   2018-12-27 19:21:00
记得哦
楼主: shps951015 (宝宝QQ)   2018-12-27 19:34:00
同意C大,有写单元测试就是一种保障
作者: mozume (米虫)   2018-12-27 19:44:00
我喜欢这句“注解会骗你,但程式码不会骗你”遇过的太多次注解跟code完全不合的,年代越久远的越多
作者: MOONY135 (谈无欲)   2018-12-27 20:13:00
让我们感谢那位工程师的牺牲奉献
作者: robler (章鱼丸)   2018-12-27 21:00:00
注解很多时候是在补充说明 让你可以不用把程式看完你要知道,很多程式光是看完,追踪一次就要花一整天然后方法的名子又不能写太长 注解就很有用了程式码虽然不会骗你,但是要写的让别人看不懂却很容易
作者: yyc1217 (somo)   2018-12-27 21:03:00
倒是觉得把1和2000写进注解 就是magic number的问题这两个应该是传进去的参数才对注解应该写成“超过年限就给奖金”@param int 年限 / @param int 奖金
作者: s06yji3 (阿南)   2018-12-27 21:08:00
注解应该避免写逻辑和magic number
楼主: shps951015 (宝宝QQ)   2018-12-27 21:19:00
同意y大跟S大想法
作者: googoo1102 (googoo)   2018-12-27 21:36:00
应该有个calBonus带入员工资料 然后回传奖金2000金额写在db或是档案里
作者: Jichang (C.C.Lemon)   2018-12-27 21:47:00
这程式本身就写的不好了 8000不会写在哪里
作者: lazarus1121 (...)   2018-12-27 21:59:00
大方向的注解还是必要的 不用那么细
楼主: shps951015 (宝宝QQ)   2018-12-27 21:59:00
X大,是的正常不会这样搞的,恩...我在想想举例好了
作者: lazarus1121 (...)   2018-12-27 22:00:00
至少要让人知道这段程式的主要目的是啥
楼主: shps951015 (宝宝QQ)   2018-12-27 22:01:00
我想想有没有简单不复杂的例子,可以表达我想要的
作者: lazarus1121 (...)   2018-12-27 22:01:00
我看过map包map总共包了4层的程式 没有注解我浪费半天时间读他 最后直接打掉变MultiKeyMap
楼主: shps951015 (宝宝QQ)   2018-12-27 22:08:00
之前写Java有看过这样的例子 但例子是LinkHashMap想到之前有看过在注解解释HashMap原理的....
作者: hellomotogg (你好机车)   2018-12-27 23:00:00
实作逻辑改了 method名称没改 被骗QQ
作者: xxtuoo (浪费时间不好QQ)   2018-12-27 23:38:00
类似的..老实写注解跟属名..后面人改code不改注解..更后面人怪我 注解乱写误导...以后一律只剩source..Zzz署名
作者: ppc ( )   2018-12-28 02:19:00
XDDDDDD注解解释HashMap原理也太逗
作者: rofellosx (鏖)   2018-12-28 09:33:00
不用先测试吗?
作者: DCTmaybe (竹竹人)   2018-12-28 10:44:00
问一下:所以多发的奖金有拿到手吗?
楼主: shps951015 (宝宝QQ)   2018-12-28 11:30:00
大大,抱歉让你误会了,这只是举例,实际没有发生过的
作者: MOONY135 (谈无欲)   2018-12-28 11:30:00
应该是会给 不然太没有面子
作者: b81314 (有点贵)   2018-12-28 13:12:00
这当然是举例拉- -
作者: DCTmaybe (竹竹人)   2018-12-28 13:23:00
抱歉没看到举例XDD
作者: hankyan919 (比奇堡乐队)   2018-12-28 13:24:00
这就是code review 的重要性 改功能reviewer也要看注解
作者: skizard ( )   2018-12-28 14:34:00
注解不需要写到这么细阿 让人快速带入逻辑就好
作者: Ekmund (是一只小叔)   2018-12-28 14:50:00
这case推到线上去问题不在注解吧 在验证真正伤害的是RD的时间成本 所以思考面向要变成规范注解该写些什么 使用的地方和内容比方说 只写功能 不详述规则 而是写“根据年资发奖金”但是把实际数据留在版编资讯 也好追查变化或是交给外部输入 让老板自己边看边调
作者: ggttoo (中华队加油!!!)   2018-12-28 18:38:00
推楼上的方法不错
作者: descent (“雄辩是银,沉默是金”)   2018-12-28 22:01:00
有句话说, 注解和程式码可能都是错的
作者: darkMood (瞬间投射)   2018-12-29 01:46:00
胡址,注解的功能不是其他方式可以取代,而这里的问题是没有做测试,这样改程式本来就该处死,关注解屁事更别说注解又不是这样乱写一通就可以了,少污化名注解
作者: TAKADO (朕没给的你不能抢)   2018-12-29 17:19:00
这种注解还不如不写,而且目的/逻辑应该写在文件里吧

Links booklink

Contact Us: admin [ a t ] ucptt.com