作者sec5566 (sec)
看板Soft_Job
标题[请益] 写注解到底是不是好习惯
时间Thu Dec 27 13:48:31 2018
以前上课跟书本都提到写注解，
但是我看资深同事还有接手的程式码，
都没有注解，只有我在写，
还被主管念过写注解没必要，
命名好就够了，
是我观念落伍了吗？
-----
Sent from JPTT on my Sony H4331.
--
※ 发信站: 批踢踢实业坊(ptt.cc), 来自: 223.140.72.67
※ 文章网址: https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1545889713.A.2B5.html
※ 编辑: sec5566 (223.140.72.67), 12/27/2018 13:48:43
1F：推 t64141: 想不写注解有很多前提，而这个前提不容易达到 12/27 13:54
2F：推 oneheat: 好的代码很少在写注解，或者说，code都写不好了，为什麽 12/27 13:55
3F：→ oneheat: 会觉得注解会写的好呢？ 12/27 13:55
4F：→ BeardSmallGG: 有写注解让其他人比较省时吧 五六行的程式 一句注解 12/27 14:02
5F：→ BeardSmallGG: 就知道在干嘛了 有时候哪有时间在那边一行一行看 12/27 14:02
6F：推 steve1012: 需要很多注解常常不是件好事 12/27 14:07
7F：推 deray: 写什麽注解？贴一段来看一下为什麽需要注解 12/27 14:11
8F：推 yyc1217: 觉得自己写的很好就不写注解 这种人很有问题 12/27 14:12
9F：→ yyc1217: 觉得自己写得不好而写一堆注解 这种人也很有问题 12/27 14:13
10F：→ iiiii: 写SAMPLE CODE一样道理，曲高和寡，不是人人懂你的pattern 12/27 14:14
11F：→ yyc1217: 注解是写给三个月後的自己看的 12/27 14:15
12F：推 steve1012: 不过这样讨论都打高空啦 除非你贴一段被念的程式跟注 12/27 14:21
13F：→ steve1012: 解 12/27 14:21
14F：推 stupid0319: 多练习爬code不看注解吧 12/27 14:22
15F：推 kokacal: git log是很好用的东西，每个人都在程式码内注解一段， 12/27 14:24
16F：→ kokacal: 那到底是要看程式还是看注解 12/27 14:24
17F：→ femlro: 苹果官方的code都有注解了 不写注解超越苹果 12/27 14:32
18F：推 deray: 注解！=文件 12/27 14:35
19F：→ askaleroux: 我只有Unittest写注解 12/27 14:38
20F：推 thefattiger: 我觉得至少在func/cls开头简单地写一行这是拿来干嘛 12/27 14:39
21F：推 jknm0510a: 我是会在比较复杂的判断上写注解，以後看比较不用思考 12/27 14:39
22F：→ thefattiger: 可以节省让後来阅读的人节省很多时间及不必要的猜测 12/27 14:40
23F：推 hotdogmc: 程式码本身就是注解 12/27 14:47
24F：推 Argos: 要看情况阿 你是要出API 没注解行麽？ XD 12/27 14:48
25F：嘘 abc0922001: 洗文章吗 12/27 14:49
26F：→ Argos: 内部产品程式 注解有必要再加吧 有些潜规则不讲很麻烦 12/27 14:49
27F：推 sean2449: 自以为写很好不用写注解的很多+1 通常就是...自以为 12/27 15:00
28F：推 yesyesyesyes: 要拜托 12/27 15:04
29F：推 KanzakiHAria: 拜托要+1 12/27 15:19
30F：→ KanzakiHAria: 命名到为还是需要注解 因为每个人逻辑不一样 12/27 15:19
31F：→ deray: 「当程式码与注解不符时，你相信什麽？」 12/27 15:20
32F：→ deray: 「The ultimate comment for the code is the code itself 12/27 15:20
33F：→ deray: 「注解是用来『弥补我们用程式码表达意图的失败』」 12/27 15:21
34F：→ knives: 推楼上加一，商业逻辑可以另外写在文件上去交接 12/27 15:21
35F：推 LoserWon: 会写注解的，写出去的注解越多，回来问的越少 12/27 15:29
36F：推 ymcheung: 换上有意义的命名後 注解的份量就变少了 12/27 15:38
37F：→ rofellosx: 并不会少.. 12/27 15:40
38F：→ dnabossking: 把code写的烂的一b然後跟你说：「我有写注解」看完 12/27 15:42
39F：→ dnabossking: 注解再看code发现注解根本在误导（你根本没有任何方 12/27 15:42
40F：→ dnabossking: 法保证注解的正确性跟易懂）这种人我也见过不少就是 12/27 15:42
41F：→ dnabossking: 了 12/27 15:42
42F：推 vi000246: 直接注解写文件位置 要看逻辑自己去查文件 12/27 16:02
43F：推 exeex: 先养成"程式即是注解"的code style 12/27 16:05
44F：推 iamshiao: 特殊处理写，其他不写 12/27 16:15
45F：推 kevin28: 比较复杂的逻辑才会写 12/27 16:18
46F：推 sean50301: 看情境xd 建dl模型注解一下shape 後面的人会很感谢你 12/27 16:44
47F：→ KanoLoa: 当然要写阿，写个magic搞搞後人 12/27 17:06
48F：推 twilighthook: 要拜托 文件也要写一下 12/27 17:07
49F：→ twilighthook: 不然看到A05_001.java 这样的没注解没文件鬼才知道 12/27 17:07
50F：→ twilighthook: 是要做啥的 12/27 17:07
51F：推 sachung28: 至少函式要写注解说明功能 和input/output吧 12/27 17:17
52F：推 ekin1983: 我的注解通常只写什麽时间 为何而改(bug 资安 需求单) 12/27 17:19
53F：→ ekin1983: 还有每个function上方注明用途 12/27 17:21
54F：推 channaiN2: 个人觉得都可以 不管写不写注解 只要你的code让人不好 12/27 17:24
55F：→ channaiN2: 懂 那就有改进的空间 不管是加注解或是重构 12/27 17:24
56F：推 PoloHuang: 写了注解 结果之後程式有改结果注解没跟着改 12/27 18:03
57F：→ robber1234: 4 12/27 18:44
58F：推 fanatics5566: 只有复杂的逻辑 或 work around的部分会写而已 12/27 18:44
59F：→ testPtt: 注解写得好下次回来改东西就很好进入状况 12/27 18:52
60F：→ CaptainTeemo: 那有做 code review 吗？有确保不解说的情况下对方 12/27 18:55
61F：→ CaptainTeemo: 能看懂吗？ 12/27 18:55
62F：→ testPtt: 尤其像C#注解还有函式超连结功能 追程式码方便很多 12/27 18:59
63F：推 codehard: 可以写pseudo code当注解 12/27 19:19
64F：推 overhead: 注解是用来『弥补我们用程式码表达意图的失败 12/27 19:53
65F：推 shortoneal: 你把code贴上来，不然会沦为各说各话 12/27 20:40
66F：→ shortoneal: 我有看过code写得还行购简洁，可是注解写好几行的 12/27 20:40
67F：→ shortoneal: (然後还是很整齐) 12/27 20:40
68F：嘘 THEWORLDS: 菜逼巴CODE都写不好了还不写注解 多可怜 没看过大专案? 12/27 20:52
69F：推 vn509942: 注解可以画宗教神只保佑大家身体健康 12/27 20:58
70F：推 gino0717: 注解应该写中文还英文 写英文英文太烂人家看不懂怎麽办 12/27 21:22
71F：→ f496328mm: 要写技术文件，注解还好，code 架构写得好就够了 12/27 21:27
72F：推 chuegou: 前辈写得asm没注解 看到快疯掉 12/27 21:36
73F：推 chuegou: 尤其硬体相依的设计 没注解我甚至该问ME还是EE都不知道 12/27 21:40
74F：推 ChungLi5566: 不要在注解写一堆东西 最好用两行表示整个方法 12/27 22:38
75F：推 justben: 有magic number 的时候 再写就好了 12/27 23:12
76F：→ justben: XDD 12/27 23:12
77F：嘘 xxtuoo: 几乎全部专案都我一个人维护的..写屁Zzz 12/27 23:36
78F：→ y3k: 不管Code还是注解 有必要才写 有必要必写 12/27 23:42
79F：推 molopo: 你不写 你同事也不写 可以公告一下你哪间公司吗 未来不想 12/27 23:44
80F：→ molopo: 去 12/27 23:44
81F：推 lausai: 注解是需要的 不过注解的用处是说明程式码作了甚麽 为什麽 12/28 00:26
82F：→ lausai: 这麽作 而不是怎麽做 12/28 00:27
83F：推 lausai: 不过觉得助解不需要的主管...不块陶吗XD 12/28 00:29
84F：→ gino0717: 如果当上主管就可以说 自己的code是clean code 不用注解 12/28 00:35
85F：→ gino0717: 你们底下基层都是dirty code 都给我写好写满 12/28 00:35
86F：推 CloudyWing: 我比较少写这段程式码是干嘛的，但会写为什麽要这麽做 12/28 01:01
87F：→ CloudyWing: 注解要写到到如何见仁见智，但有些写法我不敢苟同... 12/28 01:03
88F：→ CloudyWing: 像是说要写注解好维护，写一大堆，结果注解没好好维护 12/28 01:06
89F：→ CloudyWing: 或着写Log时，上行来个//Log，return来个//return 12/28 01:07
90F：→ CloudyWing: 然後最近对於一个class里有满满的regin感到很不耐烦 12/28 01:10
91F：→ coldreflect: 看公司环境，很多时候写注解commit log是纪录口头沟 12/28 01:13
92F：→ coldreflect: 通的事（避免未来被阴） 12/28 01:13
93F：推 CloudyWing: regin==>region才对 12/28 01:15
94F：→ CloudyWing: 像是field和property包一个，public method包一个 12/28 01:17
95F：→ CloudyWing: private method又包一个，method里可能验证包一个，实 12/28 01:18
96F：→ CloudyWing: 作又一个，实作里面，可能又是情况包好几个region... 12/28 01:19
97F：推 shooter555: 注解不是通常都拿来写FIXME: 和WORKAROUND: 12/28 01:21
98F：推 shooter555: 拿来注释未解决的问题与等有空再回来解0.0 12/28 01:22
99F：推 kinda: 如果写的注解能帮其他人省时间就写。地雷、reference 12/28 01:25
100F：→ kinda: 90% 的 code 不需要写。有时间写还不如多整理几次 12/28 01:26
101F：→ kinda: 改注解写太多的 code 很痛苦。注解改完还要检查很多次... 12/28 01:27
102F：推 bitcch: 最好的程式码为程式即是注解 去读读code complete就知道了 12/28 01:39
103F：→ kaltu: 可读性越低的语言越需要注解 12/28 05:27
104F：→ kaltu: ASM每个block注解很常见 12/28 05:27
105F：→ kaltu: Python本身就是可执行的虚拟码，注解远比doc string少见 12/28 05:27
106F：推 bill0205: 通常只会在写这个function拿来干嘛 或是这个档案的功能 12/28 06:41
107F：→ rofellosx: 跟可读性没甚麽关系.. 12/28 09:24
108F：→ rofellosx: 程式即是注解?程式码都看完了还需要看注解吗 12/28 09:28
109F：→ jack0204: 有时候你会看到很神奇的写法在里面，还会觉得逻辑很怪 12/28 09:30
110F：→ jack0204: 这种不写注解根本不知道它是修了什麽鬼东西才在里面的 12/28 09:31
111F：推 shellback: 我是觉得在比较难懂的地方写一两行注解有好无坏 12/28 09:36
112F：嘘 final01: 会问这问题就是只会写很废的注解吧？ 12/28 09:45
113F：→ shooter555: 话说我有看过每一行function call都写注解的 12/28 09:47
114F：推 Ekmund: 有规范的注解才是好注解 跟log、版本更新资讯一样 12/28 14:48
115F：→ robber1234: 如果一个专案做了五六年，你想都不注解会怎样 12/28 18:22
116F：推 tommyptt: 要交接的就要写吧 每个人逻辑又不一样 12/28 18:50
117F：推 ggttoo: 还是需要，不需要就不会有这个功能给你写了，重点会不会写 12/28 18:51
118F：→ BlueBird5566: 有些hard code的东西不写注解 谁知道那3小意思 12/28 21:56
119F：→ BlueBird5566: 注解就是个辅助工具 该用则用 不该用则不用 12/28 21:57
120F：→ BlueBird5566: 没有好不好 而是有没有用对地方 12/28 21:57
121F：→ BlueBird5566: 就跟if 一样 看过七八层的if 看了只想翻脸 12/28 21:58
122F：→ BlueBird5566: 但也不能说用if不对 而是乱用用到没水准 12/28 21:59
123F：→ BlueBird5566: 若真的需要用到七八层if也没啥不对 但有些只要2层 12/28 21:59
124F：→ viper9709: 一楼正解 12/29 01:35
125F：嘘 darkMood: 菜岛会问/没写过大程式会问/没集体开发过会问 12/29 01:43
126F：推 TAKADO: 注解当然是写给3个月後的自己看R 12/29 17:13
127F：推 mido: 不写注解 你以为你看得懂5.6年前自己写了三小吗 12/29 19:12
128F：推 clamperni: 可以贴你被念的那段注解长怎样吗 12/29 19:26
129F：推 rahit: 我一般就每个function说一下在干嘛就好 12/29 23:46
130F：→ rahit: 写的比较复杂的部份才会特别加 12/29 23:46
131F：→ rahit: 而且常常自己写的过几个月自己也看不懂 12/29 23:47
132F：→ rahit: 注解至少让我找得到哪里要改 12/29 23:47
133F：→ superpandal: 取决於你东西写的好不好 注解、文档写不好那乾脆不要 12/30 21:13
134F：→ superpandal: 写 程式码写不好乾脆不要写...? 阿 不是 是打掉重练 12/30 21:14
135F：→ superpandal: 喜欢写大而全代码风格的喜欢用注解来维持代码可读 12/30 21:21
136F：→ superpandal: 喜欢用写小而精风格代码的喜欢用简洁易懂风格来维持 12/30 21:22
137F：→ superpandal: 代码可读性 12/30 21:22
138F：推 dabiddabid: 当你需要在数分钟内解bug，你会感激自己半年前的注解 12/31 03:18
139F：→ dabiddabid: 解 12/31 03:18
140F：嘘 lnmlee: 这总讨战文时不时就会出现 12/31 12:28
141F：→ physicsdk: 应该要是好的，但有些注解写得跟实际不同，反而误导 12/31 14:20