作者iincho (世界的尽头)
看板Soft_Job
标题Re: [请益] 写注解到底是不是好习惯
时间Sun Dec 30 07:41:26 2018
※ 引述《accessdenied (存取违规)》之铭言：
: 这边怎麽老是吵着小孩子头上有几根毛的问题。
: 说不用注解的，都是英雄主义作祟，自己因为自己的程式码天下最简洁易懂，这种看不清
: 自己的人还挺多的。
: 团队合作就是要注解，除非你不在乎团队！
: 你以为大家都是你肚子里的蛔虫？
: 我光是写一行code：
: key = salt + DateTime.Now.AddHours(-4).ToString(“MMdd”);
: 就会一直有人来问为什麽要这样写，-4什麽意思？
: 最後我加上一行注解从此耳根清净
: // 厂商要求每天清晨4点以後要更换加密金钥
: 大家讲了半天，注解只有一个缺点，就是过时美人维护。而我认为这才是真正该教育改善
: 的文化和心态：不是我写的注解，所以我没有维护的责任。
: 这才是真正的弊端，而不是倡导clean code。
这个例子举得蛮好的，很多时候我们实务上面对的问题不是单靠命名就可以解决，
因为很多问题没有逻辑性。
比如说我有个机器硬体设计可能有问题，操作100次的时候需要有一个例外操作，
这个code可能会长成:
for(int i = 1 ; i <= 2000; i++){
if(i % 100 == 0){
DoSomethingElse();
}else{
DoSomething();
}
}
这种case你要怎麽命名? 这可能是个hardware bug，你确定你要在变数
里面解释这是一个hardware bug吗? 这个case跟上面举的-4基本是同一类的，
你变数再怎麽命名都不会比写注解清楚。因为实务上我们会想要提醒接手
的人这个hardware bug长什麽样子，如果有做类似的操作要怎麽避开，
这不用注解是不大可能做得到的。如果你说可以写在commit log...
ㄛ...我们好像有客户还在用svn...
这种例子我觉得不能算是magic number，本质上不管你怎麽define都解释不清楚，
用define的好处就是集中管理方便重用而已。真的要解释中间插两行issue number
简单说一下都好，在那边落落长想code怎麽命名花的时间不会比较少，
何况别人读你的code的时候看注解比看code上下文猜容易太多，
这个case就算加了define命名还是需要写注解。
BTW, 程式写注解和做好变数和流程命名根本就不冲突，两者是互补而不是竞争关系。
我不知道这边为什麽会有写哪一种比较好的争论，实务上两个都需要，
哪个经济用哪个。
另外我真的觉得很好奇想认真问一下，各位真的觉得那个-4在那边取什麽
DailyRest之类的东西绕来绕去有比加一行注解好吗...??
先不要说是不是大炮打小鸟这问题，code没有比较好读啊。
--
※ 发信站: 批踢踢实业坊(ptt.cc), 来自: 220.134.180.133
※ 编辑: iincho (220.134.180.133), 12/30/2018 08:24:29
1F：推 GX90160SS: 其实很多时候跟每个人所在环境不同关系很大 12/30 08:25
2F：→ GX90160SS: 举例就可以看出原PO不是走纯软的吧，应该没有对程式 12/30 08:26
3F：→ GX90160SS: 设计规范有所要求，从coding style可窥知一二 12/30 08:26
我那也是随便举个例子。
我就表达一件事，再怎麽精心设计变数名称和流程不可能cover所有case，
注解不可少，该用就要用。
※ 编辑: iincho (220.134.180.133), 12/30/2018 08:28:27
4F：→ GX90160SS: 有些环境需要review code的机会可能不多就不会注重这块 12/30 08:29
code review我们有做啊，没加注解一样会被我踢。
※ 编辑: iincho (220.134.180.133), 12/30/2018 08:30:08
5F：→ GX90160SS: 但也有多人协同工作的公司是天天要整合别人的程式码 12/30 08:30
6F：推 GX90160SS: 注解有其必要，但是不是写了注解就可以对程式可读性 12/30 08:34
7F：→ GX90160SS: 便宜行事，注解这东西不像变数可以跟着程式到处跑 12/30 08:34
呃..这两件事根本不冲突啊，没有人说写了注解就不需要考虑程式可读性?
是有一派坚持写注解是你程式写不好这论点比较有问题吧..?
※ 编辑: iincho (220.134.180.133), 12/30/2018 08:39:09
8F：推 superpai: 你想要注解的是why , 但是-4 是what, 不大相同 12/30 08:39
9F：推 superpai: 所以-4跟你的100都要命名，然後加上why的注解 12/30 08:42
这个我觉得没啥问题啊，我觉得这个版实在是不知道该怎麽说...
大家对别人的东西都很picky却忽视人家要表达的东西...
以那篇-4或是我这边写的100/2000这些东西，不会因为用了define就不需要写注解。
至於您有讲到一个点，我一直都在说code可以很好表达的是what/how，但是很多情况
下why只能用注解来处理。
※ 编辑: iincho (220.134.180.133), 12/30/2018 08:46:07
10F：嘘 steve1012: 一直战这种鸡毛蒜皮到底要做啥... 12/30 08:57
11F：→ iincho: 我也觉得这种不冲突的问题发一篇也满奇怪的..XD 12/30 09:07
12F：推 hidog: -4如果只用在一个位置,我觉得要不要定义都ok 12/30 09:59
13F：→ hidog: 虽然我会定义,注解并行. 两者其实没冲突 12/30 10:00
14F：推 deray: 100拉出来变成const EXCEPTION_INTERVAL 12/30 11:56
15F：→ deray: 加个subFunction check isExceptionOccurred 12/30 11:57
16F：→ deray: 这麽简单还要我说 12/30 11:57
17F：→ xephon: 现在是变成理想派vs实务派大战? 12/30 12:26
18F：推 gmoz: EXCEPTION_INTERVAL 再怎样都会有一个名词多种脑补解释 12/30 12:43
19F：→ gmoz: 注解一行上去就解决了 干嘛坚持不要? 12/30 12:43
20F：→ localOjisan: 这个100的例子跟拒绝存取的例子有不一样吗？带有特 12/30 14:01
21F：→ localOjisan: 殊意义的值为什麽要直接hard code? 12/30 14:01
22F：推 kokal: 这例子绑定hardware,只有删除或留着,没有修改 12/30 14:23
23F：推 lance70176: 同意你的意见一票 12/30 14:53
24F：→ rofellosx: 为何不能cover所有case? 01/02 09:02
25F：→ fgkor123: 韧体常不能cover，粒度不够+记忆体限制+不一定有os... 01/04 07:48
26F：→ fgkor123: i/o没事不会重写，special case常常比想像的多... 01/04 07:49
27F：→ viper9709: 推这篇~解说的很好 01/04 22:24