作者alihue (wanda wanda)
看板Soft_Job
标题[心得] 好的注解是解释为何需要这段 code
时间Fri Mar 19 22:35:42 2021
转自推特
https://twitter.com/BenLesh/status/1372562839475470336?s=20
Add comments about WHY code exists, not what it does.
The code is right there, we know what it does.
注解应该用来解释这段 code 的背景需求/含意，
而不是把 code 表面上的意思再讲一次
ps. 推特内有范例图
https://i.imgur.com/fNQakeb.jpg
还有 不要尽相信 code 即是注解，
有时给你开 debug mode 你还是不晓得为何要这样干
ps. 版上比较少转贴型文章，试水温。reddit 蛮流行只贴链结的
https://www.reddit.com/r/programming/
--
※ 发信站: 批踢踢实业坊(ptt.cc), 来自: 106.73.26.66 (日本)
※ 文章网址: https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1616164544.A.66E.html
※ 编辑: alihue (106.73.26.66 日本), 03/19/2021 22:37:36
1F：推 cuteSquirrel: 第二张 XD 03/19 22:40
$array = array(); // array
※ 编辑: alihue (106.73.26.66 日本), 03/19/2021 22:58:58
3F：推 neo5277: login(para) //login method 03/19 23:17
4F：推 clamperni: tricky的要吧? 03/19 23:24
5F：推 cuteSquirrel: 猫猫可爱 03/19 23:49
6F：→ spfy: 以前觉得是笑话 真正遇到之後发现我自己才是笑话... 03/19 23:54
7F：→ spfy: 两千多行的递回FOR循环 注解写//循环读资料 干你娘 03/19 23:56
8F：推 cuteSquirrel: XDDDDDDDDD 03/19 23:57
9F：推 drajan: 认同 03/20 00:00
10F：推 chuegou: #define ZERO 0 //origin 03/20 00:09
11F：推 ctrlbreak: 注解都是在骂老板、表同事 03/20 00:10
12F：推 Sixigma: 最好的code本身应该要解释它自己，很多注解很容易写废话 03/20 00:34
13F：推 cuteSquirrel: 真的 看到self-explanatory code效率高很多 03/20 00:36
14F：推 drajan: Code 只能解释 what 注解跟文档可也解释 why 03/20 00:37
15F：推 pikaka: 本文有提到不要尽相信code即是注解 就是因为 03/20 00:51
16F：→ pikaka: 没有那麽多最好的code阿XD 03/20 00:51
17F：→ pikaka: 能在注解多给可能有用的资讯 对後面接手的人都是有帮助的 03/20 00:57
18F：推 Sixigma: 我同意没那麽多"最好"的code，但这是可以改进的方向 03/20 01:10
19F：→ wawi2: 可是一堆人写的code就是让人看不懂阿 阿对了 有些人英文 03/20 01:22
20F：→ wawi2: 不太好 写了注解也是让人没看懂 03/20 01:22
21F：推 anandydy529: //下班前突然来一颗陨石，所以这样写才能正常下班 03/20 02:26
22F：推 t22251974: 谢谢分享 03/20 02:34
23F：→ VdustR: code 可以自己解释在做什麽 注解用来解释为什麽要这样做 03/20 04:18
25F：→ jobintan: 安心しろ！老板要是刻意挑刺，无论注解解释的再清楚总是 03/20 06:52
26F：→ jobintan: 会有意见的。 03/20 06:53
27F：→ jobintan: 只是清楚的注解让後面接手能短痛接手，就写进linked in 03/20 06:55
28F：→ jobintan: profile里面，当做自己的credit。 03/20 06:55
29F：推 aidansky0989: 同意，很多code需求都要写清楚，没有注解靠通灵 03/20 08:14
30F：推 hduek153: //不知道为什麽加了这行才能动 03/20 08:50
31F：→ OrzOGC: 对不起 我也这样写...QQ 03/20 08:56
32F：推 mathrew: //Google到的，我也不知道为什麽 03/20 09:08
33F：推 v7q4: // for test 03/20 09:45
34F：→ v7q4: 结果那行拿掉就挂了…明明是必要的啊！为何要写for test.... 03/20 09:46
35F：推 ssd860505da: 猫咪<3 03/20 09:55
36F：推 stupid0319: // something to do 03/20 10:21
37F：→ superpandal: 有看过解释来龙去脉很多行但如同没讲的状况吗？ 个人 03/20 10:31
38F：→ superpandal: 还是习惯Keep it simple and flexible 03/20 10:32
39F：→ leo5916267: 我觉得注解可以写这程式用在哪里，比写他在干嘛好， 03/20 10:45
40F：→ leo5916267: 程式在干嘛应该表现在命名上 03/20 10:45
41F：推 t19960804: //shit code 03/20 10:48
42F：→ superpandal: 用在哪与在做什麽很容易写的差不多 命名也要看长度 03/20 10:53
43F：→ superpandal: 驼峰命名太长会很悲剧 唯一支持_ 03/20 10:54
44F：→ superpandal: 不过已有的系统就没办法了 全小写+下划线非常清爽 眼 03/20 11:00
45F：→ superpandal: 球无压力 03/20 11:00
46F：推 bronx0807: if {...} // end of if 03/20 11:03
47F：推 howard50009: 同意，推这篇 03/20 11:17
48F：推 lturtsamuel: 看过最实用注解是 // 千万别在这函式前 aquire mutex 03/20 11:42
49F：→ energyy1104: //stackoverflow的连结 03/20 11:48
50F：推 shibin: 同意，谢分享 03/20 12:07
51F：推 SKII588: 需要撇清责任时会写，某年某月某董要求修改之类的 03/20 12:08
52F：推 CarpeDiemAL: // Wtf is this? stubbed. 03/20 12:35
53F：推 molopo: //我先走了 剩下交给你了 03/20 12:56
54F：→ Csongs: //看不懂 块陶啊 03/20 12:57
55F：推 WaterLengend: 认同 03/20 12:59
56F：推 foodordertw: // here could be a bug 03/20 13:33
57F：推 lee457088: // Pasted from web. Idk why it works. 03/20 13:39
58F：推 Nigger5566: // 干你老师好想下班 03/20 13:58
59F：推 leftless: //SNIS-OOO 03/20 14:47
60F：推 cuteSquirrel: // just workaround 03/20 15:03
61F：嘘 online135: // 垃圾欺负新人的 senior 都去死 03/20 15:51
62F：→ WunoW: 楼上怎麽了?? 03/20 16:06
63F：推 Muscovy: 我看过想一套, 写一套, 注解一套, 每套不一样还分版本. 03/20 16:18
64F：→ Muscovy: 最好玩的是程式跑起来还没问题... 03/20 16:19
65F：推 hamster3933: 推 03/20 16:50
66F：→ online135: 没有我留错地方了哈哈哈 03/20 17:52
68F：推 abc0922001: 我抱怨需求都是写在 commit 里 03/20 18:47
69F：→ jobintan: 哪天干得不爽，在离职走人前将重要的code全注解掉。（误 03/20 19:51
70F：→ jobintan: BTW，整串的怨念感觉深不见底，之前看过TechLead的影片 03/20 19:54
71F：→ jobintan: 也许能参考下，网址在此： 03/20 19:55
73F：→ jobintan: 不然去YT搜" anti-patterns techlead"就找得到了。 03/20 19:59
74F：→ jobintan: 这招注解还狠… 03/20 20:00
75F：嘘 wulouise: linux kernel有一行程式配五十行注解说不用lock的原因 03/20 21:37
76F：→ wulouise: 靠腰按错碰到嘘，等等补推 03/20 21:37
77F：推 wulouise: 补推 03/20 21:45
78F：嘘 jamesho8743: 是不要相信注解即是code吧 code本来就是绝对存在的 c 03/20 22:13
79F：→ jamesho8743: ode才是真正在run的 注解并不靠谱 03/20 22:13
80F：推 jej: // 我在绝情谷底 嗡嗡嗡 03/20 23:13
81F：推 marc47: 如果你有写过go的code你就不会这样说了，光是变数明名跟fu 03/21 01:06
82F：→ marc47: nc动名词，就可以写完详细的说明文件，然後加上func的标记 03/21 01:06
83F：→ marc47: 注解及一个README.md就整份文件写完收工 03/21 01:06
84F：推 lturtsamuel: 我看你是没看过两个go channel互相咬住 要写注解警告 03/21 01:44
85F：→ lturtsamuel: 接手者不要在一个channel返回前往另一个channel塞值 03/21 01:44
86F：推 twonia: 我觉得适度可以，但多半是大公司内被转了不知道几手的Code 03/21 08:16
87F：→ twonia: 中间改的人不见得有维护注解，也不是人人都有能力写好让人 03/21 08:16
88F：→ twonia: 可以理解用途的Code，更该是个相辅相成的东西 03/21 08:16
89F：推 azureroki: 看过写//独立 的... 03/21 08:30
90F：→ ketrobo: // 不写不能下班 03/21 10:15
91F：推 markbex: code只能解释做了什麽 但无法解释为什麽这麽做 03/21 14:15
92F：→ markbex: 把意图、Why要写在注解里面，常常帮助到的是未来的自己 03/21 14:15
93F：→ leolarrel: #不知道为什麽不能用//当注解,所以就改成# 03/22 10:33
94F：→ leolarrel: 针对markbex大大的需求,版控summery更加的适合 03/22 10:34
95F：→ MoonCode: 提到golang直接看标准库 03/22 12:13
97F：→ MoonCode: 注解写非常多而且详细 03/22 12:13
98F：→ MoonCode: 有谁可以只用code表达所有事物的人我只能说你厉害喔 03/22 12:14
99F：→ jobintan: 光看Code不看注解就知道这段Code是作啥，那也很强大。 03/22 12:25
100F：→ shooter555: 只看code可以理解他做啥 厉害的不是看得人 是写的人 03/22 13:47
101F：→ shooter555: 不相信注解不是因为能不能写的详细 是因为通常会忘了 03/22 14:02
102F：→ shooter555: 维护 03/22 14:02
103F：嘘 jamesho8743: 注解的问题是有可能误导 有维护性的问题 就算它写的 03/22 16:02
104F：→ jamesho8743: 时候是ok的 但後来code变更时注解是否也同时更新? 03/22 16:02
105F：→ jamesho8743: 注解跟code不一样时还不是得看code 03/22 16:02
106F：推 lwecloud: //Magic number 03/22 16:56
107F：→ pikaka: 楼上提到维护性的问题 code本身也有阿 什麽东西不好好维护 03/22 19:22
108F：→ pikaka: 都会遇到问题 这种情况有问题的都是人 不是这工具 03/22 19:22
109F：推 s0914714: //更多更详尽程式码 在Stack Overflow 03/23 01:08
110F：→ s0914714: code是本体 注解是辅助让code更完善 彼此相辅相成 03/23 01:11
111F：推 jamesho8743: 这个所说的维护性问题应该是说一致性问题 code没有一 03/23 08:31
112F：→ jamesho8743: 致性问题 不管写得再烂 它跟实际上run的是完全一致 03/23 08:31
113F：→ jamesho8743: 因为一致性问题 所以注解要随时维护得跟code一样 03/23 08:33
114F：→ cha122977: 注解麻烦在维护 当然可以说我看code最准哪需要管注解 03/23 09:04
115F：→ cha122977: 但不一致时你不知道是code写错了 还是注解没更新… 03/23 09:05
116F：嘘 jamesho8743: 这就是注解麻烦的一面 容易误导 基本上code"不会错" 03/23 20:44
117F：→ jamesho8743: 注解可以无视 code 就是现在run起来的样子 如果不 03/23 20:44
118F：→ jamesho8743: 对不符合需求 就改code 03/23 20:44
119F：→ jamesho8743: 注解跟code不一致时 基本上你根本不要管注解 因为注 03/23 20:49
120F：→ jamesho8743: 解通常是更新度比不上code 你要做的只是把code run 03/23 20:49
121F：→ jamesho8743: 一遍 看看是不是符合预期 在意注解变成它在混淆你 03/23 20:49
122F：推 jamesho8743: 所以说为什麽注解最好只解释架构或者作者的意图 不要 03/23 20:54
123F：→ jamesho8743: 去写太过细节的东西 因为架构跟意图通常不容易随时 03/23 20:54
124F：→ jamesho8743: 间而改变 要把注解的其它功能 放在把code写得清楚易 03/23 20:54
125F：→ jamesho8743: 懂上面 清楚易懂的code本身就是一种注解 03/23 20:54
126F：→ yyc1217: 更多的是觉得自己写得很好所以不用加注解 03/23 21:08
127F：推 b85040312: 像我公司都直接不注解的 注解还会被呛，看 code 就不好 03/23 21:17
128F：推 cuteSquirrel: 哈 还有遇过会删注解的 XDDDDD 03/24 12:03
129F：→ shooter555: 注解就是用来//WORKAROUND:XXX //TODO:XXX //FXCK:XXX 03/24 13:04
130F：→ shooter555: 用来解释给後面维护的人知道原因 以面被骂 那个废物前 03/24 13:07
131F：→ shooter555: 辈写这什麽鬼扣 03/24 13:07
132F：→ shooter555: 以免 03/24 13:08
133F：推 jamesho8743: The code is right there, we know what it does. 英 03/24 18:19
134F：→ jamesho8743: 语这两句讲得很好 都讲完了 03/24 18:19
135F：→ mrnegativetw: // TODO 03/25 18:48
136F：推 mmppeegg: 注解好好写啦 对你自己好 03/29 14:30
137F：→ mmppeegg: 不要哪天你回来看你自己的code都看不懂 03/29 14:30
138F：→ viper9709: 推楼上 03/29 23:56
139F：→ BoXeX: 你的code功能太简单才能光靠code表达 常常一些code都是 04/01 15:14
140F：→ BoXeX: 为了某个special case存在的 不靠注解谁知道用意 04/01 15:14
141F：→ BoXeX: 当然也可以靠commit讲啦 但对读的人来说就是麻烦 04/01 15:14
142F：→ BoXeX: 在那边说好的code不需要注解的 往往只是给自己的懒惰找 04/01 15:16
143F：→ BoXeX: 藉口 04/01 15:16
144F：推 molopo: 拜托不写注解 乱命名的 独立接案就好 不要出来害人好吗 01/19 12:44