团队开发代码不爱写注释，如何解决这一困境？
labulaka521 · labulakalia · 2020-10-22 23:19:40 +08:00 via iPhone · 10286 次点击这是一个创建于 1500 天前的主题，其中的信息可能已经有所发展或是发生改变。
刚入职不久，维护的心累，在别人的没有注释代码上加功能是真的难受
怎么让大家对于比较复杂的逻辑习惯写上注释
怎么让大家对于比较复杂的逻辑习惯写上注释
第 1 条附言 · 2020-10-23 10:44:52 +08:00
个个都说自已代码写的很优雅 结果一翻代码 ifelse 先循环个五六层 这就是所谓的优雅 算了 环境导致 就这样吧 自已写的 写好注释能让以后的自已或者别人看懂就行了
 |
1
Hider5 2020-10-22 23:26:43 +08:00
赶快跑
|
 |
2
labulaka521 OP @Hider5 我是真不知道是大家都是这样还是只有这里是这样
|
 |
3
thedrwu 2020-10-22 23:32:45 +08:00 via Android
换 haskell，不用写注释
|
 |
4
kaiki 2020-10-22 23:34:23 +08:00  1
不写注释我昨天写的代码今天都看不懂，估计他们的代码自己不会看吧
|
 |
5
az467 2020-10-22 23:35:58 +08:00 2
拒绝注释比例过少的 commit 。
|
|
6
labulaka521 OP @az467 这我决定不了，只是刚进去的小兵 ，只能发发牢骚或者提点意见
|
|
7
labulaka521 OP @kaiki 哎 谁知道呢 每次改个东西 就很难受 醉了
|
|
8
labulaka521 OP @thedrwu 这是什么鬼
|
 |
9
UsherOu 2020-10-22 23:43:42 +08:00
我们 cto 不让写注释
|
|
10
labulaka521 OP @UsherOu 这能给个理由吗
|
 |
11
billlee 2020-10-22 23:54:21 +08:00 1
@labulaka521 #10 遇到过注释和代码不同步的，错的注释不如没注释
|
|
12
labulaka521 OP @billlee 改了代码 没改注释吗
|
 |
13
Cuo 2020-10-23 00:22:49 +08:00 1
|
|
14
Cuo 2020-10-23 00:23:36 +08:00
# 10 这能给个理由吗
|
|
15
labulaka521 OP @Cuo 好代码的确具有可读性 ，但是不是所有代码都能是好代码
|
 |
16
abersheeran 2020-10-23 00:53:12 +08:00
你这个问题直接让我思绪回到一年前我还在某公司的时候……Django1.3 配上 Python2.6，业务代码就是堆，这个无可厚非，一个 URL 一个函数嘛，反正也不影响整体项目。但代码结构也是屎，统一的 JSONResponse 都没有，一个单语句的函数，非要放进一个类里去调用。注释？你想要什么注释？我提出了这个问题……被教育了一顿。我提出优化代码，我又被教育了一顿，“自然有人来做，你把业务写好就行”。
待了一个多月，掐点看学校的实习任务完成了，直接跑路。 |
 |
17
qiumaoyuan 2020-10-23 00:55:29 +08:00
重构代码
|
|
18
qiumaoyuan 2020-10-23 00:58:50 +08:00
写详细点吧：
1. 代码需要注释说明代码不可读，为了让代码可读，就需要对代码进行重构。写注释本身属于重复行为——已经用代码写了一遍，再用人类语言写一遍，一处变动需要同时做两处修改。 2. 重构代码不需要先理解原有逻辑，逻辑在重构过程中自然就能理解。 |
|
19
labulaka521 OP @qiumaoyuan 代码注释说明代码不可读，这我感觉有点极端了，像一些项目比如 grpc go-micro 都有每个函数或变量都有很详尽的注释，我觉得是注释是帮助来理解代码逻辑的，而不是代码不可读了，才需要注释。
|
|
20
Cuo 2020-10-23 01:38:26 +08:00
@labulaka521
#15 好代码的确具有可读性 ，但是不是所有代码都能是好代码 review 时有读不懂的地方直接指出来让对方改。如果是比较复杂的设计则请对方连带文档一起提交。 或者看看以前的工资单，年终奖忍一忍也就过去了（狗头） |
 |
21
boris93 2020-10-23 01:51:53 +08:00 via Android
我司，跨国美企，也这样
更不用说还能见到各种匪夷所思的脱裤子放屁写法 非英语国家的人写的注释，有可能还得琢磨一阵才能看明白 对我来说，业务清晰（至少在我自己看来清晰）的代码我不写注释 对于日后可能看不懂的，或者当时就玩命网上冲浪才憋出来的代码，我会写很多的注释，并且可能附上参考文档链接 |
 |
22
raaaaaar 2020-10-23 07:11:53 +08:00 via Android
找 leader ？拿个垃圾代码过去问他看不看得懂，引导他自己提出规范的重要性。
|
 |
23
ferock 2020-10-23 07:22:19 +08:00
自己判断，代码是否可读
技术方案文档，另外写 代码上附上链接。 代码定期内部 code review 。 别人如果看不懂你的代码，那就应该附上注释，最好重构。 所以，团队合作写代码，规范很重要！ |
 |
24
AkideLiu 2020-10-23 07:55:44 +08:00 via iPhone
换 assembly 吧，今天不写注释明天就看不懂了
|
 |
25
line 2020-10-23 08:20:46 +08:00 via iPhone
大部分情况，可以用 git commit message 代替 commit 勤快点就行
|
 |
26
user8341 2020-10-23 08:22:03 +08:00
刚入职不久就别妄想去改变公司既有的习惯。好好适应一年。
|
 |
27
kemikemian 2020-10-23 08:22:06 +08:00
你待的时间久了自然也不写了,还没融入集体
|
 |
28
djs 2020-10-23 08:41:56 +08:00 via iPhone
良好的命名比瞎写的注释更优秀，前提是良好的命名
|
 |
29
nicevar 2020-10-23 08:44:05 +08:00
可以搭建 SonarQube 平台，提交 MR 的时候没有注释会自动拒绝
|
 |
30
jerryrib 2020-10-23 08:45:11 +08:00
 |
 |
31
sexyback 2020-10-23 08:51:10 +08:00
我找了个实习的工作，go 开发，原本想来学一下 go，结果这几天看了代码之后发现一句注释也没有，唯一的注释就是 //TO DO 这个功能尚未开发，问了带我的导师他说写注释太麻烦，看变量命名和方法名就能推算出什么意思了，学习的时候不知道注释的重要，现在终于体会到了
|
|
32
sexyback 2020-10-23 08:51:42 +08:00
@labulaka521 咱俩估计一样，我们公司的代码就没有注释
|
|
33
labulaka521 OP @djs 确实是
但是我们这边存在的情况是有些被重构的函数 迁移的字段 但是为了兼容还是保留原有的 这些几乎都没有注释 有些时候的用老的函数 老的字段偶尔就会出现异常 |
|
34
labulaka521 OP @sexyback 其实 go 还好 但是我们这边是 py 吗呀 函数参数一大堆 几乎没有注释 只有追到函数内部后才可以看到这个参数的类型 是干啥的
|
 |
35
xianxiaobo 2020-10-23 08:53:12 +08:00 1
你来当老板或者领导，告诉大家注释最重要，可以开发的慢，但是一定要写注释，每天快下班前由技术领导统一检查今天的代码写注释了没。
|
|
36
labulaka521 OP @xianxiaobo 想认真回复就认真回复 别这样阴阳怪气的 OK ？没看前面的吗？
|
 |
37
jorneyr 2020-10-23 08:58:40 +08:00
把自己写的代码也像 JS minify 那样搞一下，大家一起看不懂
|
 |
38
Leigg 2020-10-23 09:00:52 +08:00 via Android
这个没办法，以后你会经常遇到，除非老大提出来解决，否则都是看个人心情，你现在不懂哪里就问，不过最后先看完整体逻辑，再提问，自己写好注释
|
 |
39
xiaoxinxiaobai 2020-10-23 09:02:35 +08:00 via Android
你读一遍代码给加上注释
|
 |
40
notejava 2020-10-23 09:03:38 +08:00
可读性强的代码就是最好的注释。如果代码本身就逻辑混乱，也别指望注释了。
|
|
41
notejava 2020-10-23 09:05:28 +08:00
可读性强的代码就是最好的注释。如果代码本身就逻辑混乱，别指望他能写出好的注释。
|
 |
42
zsyld 2020-10-23 09:05:38 +08:00
辣鸡代码才需要注释（狗头
|
|
43
djs 2020-10-23 09:07:54 +08:00 via iPhone
@labulaka521 悲伤
|
 |
44
elintwenty 2020-10-23 09:09:53 +08:00
既然制定不了规范就不要管了，比起没有注释，过时的、失效的注释是更大的灾难。如果不能保证你的、甚至因你而出现的注释鲜明有效，那么还是完全没有更好。可以尝试要不要引入一些自动化的工具来建议主管去考虑
|
 |
45
maddot 2020-10-23 09:11:36 +08:00
函数名称就是最好的注释
|
 |
46
zsdroid 2020-10-23 09:12:07 +08:00 1
看了上面这么多楼的发言，感觉 jdk 特别垃圾，因为注释特别多。
 |
 |
47
4771314 2020-10-23 09:12:30 +08:00
基本的注释还是要有吧，不然谁看得懂？
代码是写给人看的，不是写给计算机看的。 |
|
48
labulaka521 OP @notejava 是的 但是还存在一些被重构 被迁移的字段 函数 几乎都没有注释 用了旧的函数 字段偶尔就会报错
|
 |
49
idoggy 2020-10-23 09:14:31 +08:00 via Android 1
注释基本都是用来写 why 和 how 的，很少写 what 的，看事情不要二极管
|
 |
50
alcoholpad 2020-10-23 09:16:19 +08:00
良好的函数名, 变量名 就是最好的注释, 函数尽量短小. 如果像写文章一样认真写代码, 根本不需要注释.
毕竟代码的修改会经常忘了同步注释, 更容易让人误解. |
 |
51
UmiKz 2020-10-23 09:18:34 +08:00
开发规范做到见名知其意，注释少些，也影响不大
|
 |
52
watzds 2020-10-23 09:20:00 +08:00 via Android
这不是挺正常吗？
|
 |
53
zjsxwc 2020-10-23 09:20:39 +08:00
除非复杂的业务逻辑我会先写注释后写代码做填空题，同时会引用产品经理具体需求描述的 issue id 方便后续跟进，还有这种复杂的业务由于不具备可复用性，我基本都是写在一个大方法里面。
大部分时候业务逻辑等价于 4 、5 个 sql 查询的就不写注释了，这种猜都能猜到是在干什么。 |
 |
54
darktutu 2020-10-23 09:25:40 +08:00
我遇到过注释和代码不匹配的，更痛苦，还不如没有注释呢。
|
 |
55
aydd2004 2020-10-23 09:30:29 +08:00 4
说真的 我给自己写的东西都加一堆注释
这些人哪里来的勇气 |
|
56
UsherOu 2020-10-23 09:30:55 +08:00
@labulaka521 代码即注释，见名知意
|
 |
57
darkforest8848 2020-10-23 09:31:59 +08:00
@jerryrib 兄弟 bannner 能发下吗
|
 |
58
zhangyangkam1 2020-10-23 09:34:50 +08:00
改变不了环境可以从自己做起
|
 |
59
faceRollingKB 2020-10-23 09:36:36 +08:00
时间不够
|
 |
60
JamesR 2020-10-23 09:45:47 +08:00
外包做的，时间不够嘛。
|
 |
61
ungrown 2020-10-23 09:47:05 +08:00 1
注释其实算是个历史遗留产物
以前计算设备算力低，开发机的算力也低 自然也没有如今功能强大的 IDE 软件辅助写代码 所以那时候代码字词句能少就少尽量简洁 那么代码的含义就很难从代码本身看出来，需要注释 现如今在 IDE 的自动补全代码树监控的加持下 长名超长名蔚然成风 代码含义几乎可以完全通过合理命名来显示表达 “代码即注释” 只有很少的情况下，才不得不依靠注释进行说明，例如： 命名无法体现含义，亦或妖码怪码 bug 码不讲道理，亦或“知其然不知其所以然”的代码 |
 |
62
tikazyq 2020-10-23 09:49:49 +08:00
这种项目，当你花了半天时间读懂的时候，需求已经变了，淡定
|
 |
63
jatsz 2020-10-23 09:50:16 +08:00 1
代码不会说谎，注释会。
|
|
67
jerryrib 2020-10-23 10:10:16 +08:00
|
 |
68
ligiggy 2020-10-23 10:14:49 +08:00
理清业务逻辑可以写注释，封装接口给人用要文档。但是如果每一个函数，每一个命名都要写注释，那才是最垃圾的。代码要提升的是可读性，而不是人人口中的“注释”。
|
|
69
jatsz 2020-10-23 10:20:37 +08:00
|
 |
70
matrix67 2020-10-23 10:21:59 +08:00
上 ci，没注释拒绝合入
|
|
71
xianxiaobo 2020-10-23 10:24:51 +08:00 1
@labulaka521 我想说的是，如果你不是领导或者老板，根本没办法。写注释确实是减少了维护成本，但是增加了开发时间啊。谁来为这部分买单呢？另外，我说的确实是解决办法，不完全算是阴阳怪气。
|
 |
72
sunznx 2020-10-23 10:24:54 +08:00
见过 curd 还加注释的
|
|
73
sunznx 2020-10-23 10:25:27 +08:00
见过 curd 还加注释的
// 获取一个用户 // 删除一个用户 这种注释还不如不注释 |
|
74
qiumaoyuan 2020-10-23 10:32:55 +08:00 2
@labulaka521 注释的作用主要是说明代码为什么要这么做，而不是描述代码在做什么。
另外软件开发就是要极端。没有极端过，你根本不知道“中间”在哪里，不知道极端在哪，所谓的折衷、权衡都是在搞笑和自慰。 |
 |
75
fyooo 2020-10-23 10:37:46 +08:00
国内大环境根本解决不了，这类需要从上至下的推动的
|
 |
76
casillasyi 2020-10-23 10:52:19 +08:00 1
代码写的一塌糊涂的，需要注释才能看懂的，你以为他注释写的你能看懂吗？
|
 |
77
wysnylc 2020-10-23 10:53:24 +08:00
@qiumaoyuan #74 学数学的时候恨不得注释多的拉满,到自己写代码就觉得注释麻烦没意义笑死了
|
 |
78
Still4 2020-10-23 10:57:15 +08:00
@darktutu 需求变了，注释没改，我们这跟没写注释是一个原因，需求压力大，很多时候上午提需求晚上上线，谁想让后来人指着自己鼻子骂呢，时间不允许没办法，优先保证东西正常，注释都是想着后面再说，一拖就没影了
|
 |
79
northisland 2020-10-23 11:04:26 +08:00
一行注释都没有的是垃圾；不分巨细，全注释的也是垃圾。
还是武侯祠「攻心对联」里的那一句“不审势，则宽严皆误”。 （但对于外行领导，想通过 5 分钟 code review 就深入理解我做的事情，目测领导也是垃圾。） |
 |
80
lk920724 2020-10-23 11:09:44 +08:00
这样想，没注释总比过期注释要好。
|
 |
81
sdushn 2020-10-23 11:16:39 +08:00
做 cr 啊，看不懂的，格式不对的都不让合入，
|
 |
82
djyde 2020-10-23 11:34:48 +08:00 1
注释不是用来解释这段代码在做什么，而是告诉后来的人为什么要写这段代码。
|
 |
83
paoqi2048 2020-10-23 11:35:24 +08:00 1
楼上一堆洗的，希望你们以后的同事都不写注释哈
|
 |
84
haha512 2020-10-23 11:46:29 +08:00
看了上面回答，应该把第一个设计代码要加注释的人拉出来痛打一顿。
v2 任何一个问题下面， 总少不了一堆的“逼王之王”，为什么呢 |
 |
85
pangleon 2020-10-23 12:01:11 +08:00
让 AB 互相改他们之前做的大需求，然后看他们对喷
|
|
86
labulaka521 OP 3
@haha512 没办法 总有人觉得我的代码很优雅 很优雅 不用注释 结果一看 是什么玩意 叠加五六层 ifelse 真逼王之王
|
 |
87
lululau 2020-10-23 12:16:45 +08:00
业务代码不需要注释，类名和方法名就是注释，把 PRD 写写好是最重要的
|
 |
88
opengps 2020-10-23 12:26:28 +08:00
写注释奖钱啊，很多人不写，不就是因为大部分企业都卸磨杀驴吗
|
|
89
wysnylc 2020-10-23 12:29:54 +08:00
|
|
90
Leigg 2020-10-23 12:36:21 +08:00 via Android
楼上一帮人，个个以为光看代码就看懂了，要么是真牛逼，没遇到过垃圾同事，要么是长期混迹小公司自己就从来不写注释的，别人问还怼别人的。
哪个比例更高一点？ |
 |
91
Huelse 2020-10-23 13:06:51 +08:00
当然是能一起商量好最好
实在不行就你写的时候完全不按套路命名来写即可，注释留在自己的仓库，commit 的时候去掉注释 |
 |
92
zerofancy 2020-10-23 13:16:52 +08:00
lint
|
 |
93
tony1890 2020-10-23 13:21:48 +08:00
没办法。只能管好自己。虽然我跟同事说过多次，不用的代码要么注释要么删除，方法最起码说明是干嘛的，公共方法还要写入参和 returns，公共组件要写文档。balabala 一堆。
然而他们很难做到。唯一欣慰的就是提交写简短记录了。 |
 |
94
newmlp 2020-10-23 13:26:18 +08:00
又不是不能用
|
|
95
darktutu 2020-10-23 13:28:44 +08:00
@Still4 是啊，所以我挺好奇的，一般项目的注释都很完善，只有我遇到的是乱糟糟的?还有就是单元测试，也是没多少或者没有，到那时看评论，大家经常都是齐备的，我也搞不明白。
|
 |
96
tabris17 2020-10-23 13:29:03 +08:00
我只在个人项目里会尽责地写注释
|
 |
97
troywinter 2020-10-23 13:51:32 +08:00
题外话，注释和代码有不同的目的，不存在好的代码不需要写注释的，他们的目的本来就不相同，有些简单的逻辑确实不需要注释，但大多数情况下，注释还是应该解释下这样设计的原因和用法，最好链接到设计文档。
|
|
98
qiumaoyuan 2020-10-23 14:01:04 +08:00
@labulaka521 也许你见过你口里描述的人，但同时你要知道这世界上真有不少人的代码是不用注释的。把无法理解的事情打个装逼的标签，把难以实现的理想当作自己不努力的借口对自己没有好处。有理就好好讲理这是程序员的基本素养，起码冰冷的机器不会照顾你的个人情绪。
|
 |
99
tankren 2020-10-23 14:19:03 +08:00
看可读性吧
|
 |
100
lazydog 2020-10-23 14:24:19 +08:00
不写注释看来是真的不行，我一周前的代码，今天看的时候竟然看不懂了，费了好长时间才反推回去。
|
Select Language