[心得] 好的注解是解释为何需要这段 code
楼主: alihue (wanda wanda) 2021-03-19 22:35:42
转自推特
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/
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/
作者: cuteSquirrel (松鼠) 2021-03-19 22:40:00
第二张 XD
作者: becca945 (频果芽子) 2021-03-19 22:53:00
作者: neo5277 (I am an agent of chaos) 2021-03-19 23:17:00
login(para) //login method
作者: clamperni (肥宅牛牛) 2021-03-19 23:24:00
tricky的要吧?
作者: cuteSquirrel (松鼠) 2021-03-19 23:49:00
猫猫可爱
作者: spfy (spfy) 2021-03-19 23:54:00
以前觉得是笑话 真正遇到之后发现我自己才是笑话...两千多行的递回FOR循环 注解写//循环读资料 干你娘
作者: cuteSquirrel (松鼠) 2021-03-19 23:57:00
XDDDDDDDDD
作者: drajan (EasoN) 2021-03-20 00:00:00
认同
作者: chuegou (chuegou) 2021-03-20 00:09:00
#define ZERO 0 //origin
作者: ctrlbreak 2021-03-20 00:10:00
注解都是在骂老板、表同事
作者: Sixigma (六西格玛) 2021-03-20 00:34:00
最好的code本身应该要解释它自己，很多注解很容易写废话
作者: cuteSquirrel (松鼠) 2021-03-20 00:36:00
真的 看到self-explanatory code效率高很多
作者: drajan (EasoN) 2021-03-20 00:37:00
Code 只能解释 what 注解跟文档可也解释 why
作者: pikaka (pipipi) 2021-03-20 00:51:00
本文有提到不要尽相信code即是注解 就是因为没有那么多最好的code阿XD能在注解多给可能有用的资讯 对后面接手的人都是有帮助的
作者: Sixigma (六西格玛) 2021-03-20 01:10:00
我同意没那么多"最好"的code，但这是可以改进的方向
作者: wawi2 (@@) 2021-03-20 01:22:00
可是一堆人写的code就是让人看不懂阿 阿对了 有些人英文不太好 写了注解也是让人没看懂
作者: anandydy529 (AndyAWD) 2021-03-20 02:26:00
//下班前突然来一颗陨石，所以这样写才能正常下班
作者: t22251974 (t22251974) 2021-03-20 02:34:00
谢谢分享
作者: VdustR (京) 2021-03-20 04:18:00
code 可以自己解释在做什么 注解用来解释为什么要这样做cra 的注解就很棒 https://tinyurl.com/2w6wd9re
作者: jobintan (Robin Artemstein) 2021-03-20 06:52:00
安心しろ！老板要是刻意挑刺，无论注解解释的再清楚总是会有意见的。只是清楚的注解让后面接手能短痛接手，就写进linked inprofile里面，当做自己的credit。
作者: aidansky0989 (alta) 2021-03-20 08:14:00
同意，很多code需求都要写清楚，没有注解靠通灵
作者: hduek153 (专业打酱油) 2021-03-20 08:50:00
//不知道为什么加了这行才能动
作者: OrzOGC (洞八达人.拖哨天王) 2021-03-20 08:56:00
对不起 我也这样写...QQ
作者: mathrew (Joey) 2021-03-20 09:08:00
//Google到的，我也不知道为什么
作者: v7q4 ((．)(．)乳剑双修 -|＝＞) 2021-03-20 09:45:00
// for test结果那行拿掉就挂了…明明是必要的啊！为何要写for test....
作者: ssd860505da (JAGER) 2021-03-20 09:55:00
猫咪<3
作者: stupid0319 (征女友) 2021-03-20 10:21:00
// something to do
作者: superpandal 2021-03-20 10:31:00
有看过解释来龙去脉很多行但如同没讲的状况吗？ 个人还是习惯Keep it simple and flexible
作者: leo5916267 (小叶) 2021-03-20 10:45:00
我觉得注解可以写这程式用在哪里，比写他在干嘛好，程式在干嘛应该表现在命名上
作者: t19960804 (泥好吗) 2021-03-20 10:48:00
//shit code
作者: superpandal 2021-03-20 10:53:00
用在哪与在做什么很容易写的差不多 命名也要看长度驼峰命名太长会很悲剧 唯一支持_不过已有的系统就没办法了 全小写+下划线非常清爽 眼球无压力
作者: bronx0807 (坚持需要练习) 2021-03-20 11:03:00
if {...} // end of if
作者: howard50009 (zxc50009) 2021-03-20 11:17:00
同意，推这篇
作者: lturtsamuel (港都都教授) 2021-03-20 11:42:00
看过最实用注解是 // 千万别在这函式前 aquire mutex
作者: energyy1104 (Bill Wang) 2021-03-20 11:48:00
//stackoverflow的连结
作者: shibin (喜饼) 2021-03-20 12:07:00
同意，谢分享
作者: SKII588 2021-03-20 12:08:00
需要撇清责任时会写，某年某月某董要求修改之类的
作者: CarpeDiemAL (CarpeDiemAL) 2021-03-20 12:35:00
// Wtf is this? stubbed.
作者: molopo (mmm) 2021-03-20 12:56:00
//我先走了 剩下交给你了
作者: Csongs (西歌) 2021-03-20 12:57:00
//看不懂 块陶啊
作者: WaterLengend (Leeeeeeeeooooooo) 2021-03-20 12:59:00
认同
作者: foodordertw (foororderTW) 2021-03-20 13:33:00
// here could be a bug
作者: lee457088 2021-03-20 13:39:00
// Pasted from web. Idk why it works.
作者: Nigger5566 (尼哥56) 2021-03-20 13:58:00
// 干你老师好想下班
作者: leftless (两个月倒一次垃圾) 2021-03-20 14:47:00
//SNIS-OOO
作者: cuteSquirrel (松鼠) 2021-03-20 15:03:00
// just workaround
作者: online135 (98分美元宇宙星尘) 2021-03-20 15:51:00
// 垃圾欺负新人的 senior 都去死
作者: WunoW (WunoW) 2021-03-20 16:06:00
楼上怎么了??
作者: Muscovy (三分熟的闹钟) 2021-03-20 16:18:00
我看过想一套, 写一套, 注解一套, 每套不一样还分版本.最好玩的是程式跑起来还没问题...
作者: hamster3933 (hamster) 2021-03-20 16:50:00
推
作者: online135 (98分美元宇宙星尘) 2021-03-20 17:52:00
没有我留错地方了哈哈哈
作者: v7q4 ((．)(．)乳剑双修 -|＝＞) 2021-03-20 18:15:00
作者: abc0922001 (中士abc) 2021-03-20 18:47:00
我抱怨需求都是写在 commit 里
作者: jobintan (Robin Artemstein) 2021-03-20 19:51:00
哪天干得不爽，在离职走人前将重要的code全注解掉。（误BTW，整串的怨念感觉深不见底，之前看过TechLead的影片也许能参考下，网址在此：https://ptt.cc/fXESYx不然去YT搜" anti-patterns techlead"就找得到了。这招注解还狠…
作者: wulouise (在线上!=在电脑前) 2021-03-20 21:37:00
linux kernel有一行程式配五十行注解说不用lock的原因靠腰按错碰到嘘，等等补推补推
作者: jamesho8743 (加拿大好美) 2021-03-20 22:13:00
是不要相信注解即是code吧 code本来就是绝对存在的 code才是真正在run的 注解并不靠谱
作者: jej (晃奶大馬桶) 2021-03-20 23:13:00
// 我在绝情谷底 嗡嗡嗡
作者: marc47 (思乐冰) 2021-03-21 01:06:00
如果你有写过go的code你就不会这样说了，光是变量明名跟func动名词，就可以写完详细的说明文件，然后加上func的标记注解及一个README.md就整份文件写完收工
作者: lturtsamuel (港都都教授) 2021-03-21 01:44:00
我看你是没看过两个go channel互相咬住 要写注解警告接手者不要在一个channel返回前往另一个channel塞值
作者: twonia (东尼。史塔克) 2021-03-21 08:16:00
我觉得适度可以，但多半是大公司内被转了不知道几手的Code中间改的人不见得有维护注解，也不是人人都有能力写好让人可以理解用途的Code，更该是个相辅相成的东西
作者: azureroki (Roki) 2021-03-21 08:30:00
看过写//独立 的...
作者: ketrobo (猫萝卜) 2021-03-21 10:15:00
// 不写不能下班
作者: markbex (马克杯) 2021-03-21 14:15:00
code只能解释做了什么 但无法解释为什么这么做把意图、Why要写在注解里面，常常帮助到的是未来的自己
作者: leolarrel (真.粽子无双) 2021-03-22 10:33:00
#不知道为什么不能用//当注解,所以就改成#针对markbex大大的需求,版控summery更加的适合
作者: MoonCode (MoonCode) 2021-03-22 12:13:00
提到golang直接看标准库https://golang.org/pkg/net/注解写非常多而且详细有谁可以只用code表达所有事物的人我只能说你厉害喔
作者: jobintan (Robin Artemstein) 2021-03-22 12:25:00
光看Code不看注解就知道这段Code是作啥，那也很强大。
作者: shooter555 (shooter) 2021-03-22 13:47:00
只看code可以理解他做啥 厉害的不是看得人 是写的人不相信注解不是因为能不能写的详细 是因为通常会忘了维护
作者: jamesho8743 (加拿大好美) 2021-03-22 16:02:00
注解的问题是有可能误导 有维护性的问题 就算它写的时候是ok的 但后来code变更时注解是否也同时更新?注解跟code不一样时还不是得看code
作者: lwecloud (CloudEX) 2021-03-22 16:56:00
//Magic number
作者: pikaka (pipipi) 2021-03-22 19:22:00
楼上提到维护性的问题 code本身也有阿 什么东西不好好维护都会遇到问题 这种情况有问题的都是人 不是这工具
作者: s0914714 (YA) 2021-03-23 01:08:00
//更多更详尽程式码 在Stack Overflowcode是本体 注解是辅助让code更完善 彼此相辅相成
作者: jamesho8743 (加拿大好美) 2021-03-23 08:31:00
这个所说的维护性问题应该是说一致性问题 code没有一致性问题 不管写得再烂 它跟实际上run的是完全一致因为一致性问题 所以注解要随时维护得跟code一样
作者: cha122977 (CHA) 2021-03-23 09:04:00
注解麻烦在维护 当然可以说我看code最准哪需要管注解但不一致时你不知道是code写错了 还是注解没更新…
作者: jamesho8743 (加拿大好美) 2021-03-23 20:44:00
这就是注解麻烦的一面 容易误导 基本上code"不会错"注解可以无视 code 就是现在run起来的样子 如果不对不符合需求 就改code注解跟code不一致时 基本上你根本不要管注解 因为注解通常是更新度比不上code 你要做的只是把code run一遍 看看是不是符合预期 在意注解变成它在混淆你所以说为什么注解最好只解释架构或者作者的意图 不要去写太过细节的东西 因为架构跟意图通常不容易随时间而改变 要把注解的其它功能 放在把code写得清楚易懂上面 清楚易懂的code本身就是一种注解
作者: yyc1217 (somo) 2021-03-23 21:08:00
更多的是觉得自己写得很好所以不用加注解
作者: b85040312 (万年newman) 2021-03-23 21:17:00
像我公司都直接不注解的 注解还会被呛，看 code 就不好
作者: cuteSquirrel (松鼠) 2021-03-24 12:03:00
哈 还有遇过会删注解的 XDDDDD
作者: shooter555 (shooter) 2021-03-24 13:04:00
注解就是用来//WORKAROUND:XXX //TODO:XXX //FXCK:XXX用来解释给后面维护的人知道原因 以面被骂 那个废物前辈写这什么鬼扣以免
作者: jamesho8743 (加拿大好美) 2021-03-24 18:19:00
The code is right there, we know what it does. 英语这两句讲得很好 都讲完了
作者: mrnegativetw (每天来点负能量) 2021-03-25 18:48:00
// TODO
作者: mmppeegg (我是寂寞的) 2021-03-29 14:30:00
注解好好写啦 对你自己好不要哪天你回来看你自己的code都看不懂
作者: viper9709 (阿达) 2021-03-29 23:56:00
推楼上
作者: BoXeX (心爱骑士团异端审判骑士) 2021-04-01 15:14:00
你的code功能太简单才能光靠code表达 常常一些code都是为了某个special case存在的 不靠注解谁知道用意当然也可以靠commit讲啦 但对读的人来说就是麻烦在那边说好的code不需要注解的 往往只是给自己的懒惰找借口
继续阅读