团队开发代码不爱写注释，如何解决这一困境？

[labulaka521]

刚入职不久，维护的心累，在别人的没有注释代码上加功能是真的难受

怎么让大家对于比较复杂的逻辑习惯写上注释

个个都说自已代码写的很优雅 结果一翻代码 ifelse 先循环个五六层 这就是所谓的优雅 算了 环境导致 就这样吧 自已写的 写好注释能让以后的自已或者别人看懂就行了

[Hider5]

赶快跑

[labulaka521]

@Hider5 我是真不知道是大家都是这样还是只有这里是这样

[thedrwu]

换 haskell，不用写注释

[kaiki]

不写注释我昨天写的代码今天都看不懂，估计他们的代码自己不会看吧

[az467]

拒绝注释比例过少的 commit 。

[labulaka521]

@az467 这我决定不了，只是刚进去的小兵 ，只能发发牢骚或者提点意见

[labulaka521]

@kaiki 哎 谁知道呢 每次改个东西 就很难受 醉了

[labulaka521]

@thedrwu 这是什么鬼

[UsherOu]

我们 cto 不让写注释

[labulaka521]

@UsherOu 这能给个理由吗

[billlee]

@labulaka521 #10 遇到过注释和代码不同步的，错的注释不如没注释

[labulaka521]

@billlee 改了代码 没改注释吗

[Cuo]

@labulaka521
可能是因为好代码本身就具有可读性吧。
而且业务逻辑本身也不需要写在注释里。我们组的注释一般是简单描述函数功能，或者标注参数类型。

[Cuo]

# 10 这能给个理由吗

[labulaka521]

@Cuo 好代码的确具有可读性 ，但是不是所有代码都能是好代码

[abersheeran]

你这个问题直接让我思绪回到一年前我还在某公司的时候……Django1.3 配上 Python2.6，业务代码就是堆，这个无可厚非，一个 URL 一个函数嘛，反正也不影响整体项目。但代码结构也是屎，统一的 JSONResponse 都没有，一个单语句的函数，非要放进一个类里去调用。注释？你想要什么注释？我提出了这个问题……被教育了一顿。我提出优化代码，我又被教育了一顿，“自然有人来做，你把业务写好就行”。
待了一个多月，掐点看学校的实习任务完成了，直接跑路。

[qiumaoyuan]

重构代码

[qiumaoyuan]

写详细点吧：

1. 代码需要注释说明代码不可读，为了让代码可读，就需要对代码进行重构。写注释本身属于重复行为——已经用代码写了一遍，再用人类语言写一遍，一处变动需要同时做两处修改。

2. 重构代码不需要先理解原有逻辑，逻辑在重构过程中自然就能理解。

[labulaka521]

@qiumaoyuan 代码注释说明代码不可读，这我感觉有点极端了，像一些项目比如 grpc go-micro 都有每个函数或变量都有很详尽的注释，我觉得是注释是帮助来理解代码逻辑的，而不是代码不可读了，才需要注释。

[Cuo]

@labulaka521
#15 好代码的确具有可读性 ，但是不是所有代码都能是好代码
review 时有读不懂的地方直接指出来让对方改。如果是比较复杂的设计则请对方连带文档一起提交。

或者看看以前的工资单，年终奖忍一忍也就过去了（狗头）

[boris93]

我司，跨国美企，也这样
更不用说还能见到各种匪夷所思的脱裤子放屁写法
非英语国家的人写的注释，有可能还得琢磨一阵才能看明白

对我来说，业务清晰（至少在我自己看来清晰）的代码我不写注释
对于日后可能看不懂的，或者当时就玩命网上冲浪才憋出来的代码，我会写很多的注释，并且可能附上参考文档链接

[raaaaaar]

找 leader ？拿个垃圾代码过去问他看不看得懂，引导他自己提出规范的重要性。

[ferock]

自己判断，代码是否可读
技术方案文档，另外写
代码上附上链接。

代码定期内部 code review 。
别人如果看不懂你的代码，那就应该附上注释，最好重构。

所以，团队合作写代码，规范很重要！

[AkideLiu]

换 assembly 吧，今天不写注释明天就看不懂了

[line]

大部分情况，可以用 git commit message 代替 commit 勤快点就行

[user8341]

刚入职不久就别妄想去改变公司既有的习惯。好好适应一年。

[kemikemian]

你待的时间久了自然也不写了,还没融入集体

[djs]

良好的命名比瞎写的注释更优秀，前提是良好的命名

[nicevar]

可以搭建 SonarQube 平台，提交 MR 的时候没有注释会自动拒绝

[jerryrib]

[sexyback]

我找了个实习的工作，go 开发，原本想来学一下 go，结果这几天看了代码之后发现一句注释也没有，唯一的注释就是 //TO DO 这个功能尚未开发，问了带我的导师他说写注释太麻烦，看变量命名和方法名就能推算出什么意思了，学习的时候不知道注释的重要，现在终于体会到了

[sexyback]

@labulaka521 咱俩估计一样，我们公司的代码就没有注释

[labulaka521]

@djs 确实是
但是我们这边存在的情况是有些被重构的函数 迁移的字段 但是为了兼容还是保留原有的 这些几乎都没有注释 有些时候的用老的函数 老的字段偶尔就会出现异常

[labulaka521]

@sexyback 其实 go 还好 但是我们这边是 py 吗呀 函数参数一大堆 几乎没有注释 只有追到函数内部后才可以看到这个参数的类型 是干啥的

[xianxiaobo]

你来当老板或者领导，告诉大家注释最重要，可以开发的慢，但是一定要写注释，每天快下班前由技术领导统一检查今天的代码写注释了没。

[labulaka521]

@xianxiaobo 想认真回复就认真回复 别这样阴阳怪气的 OK ？没看前面的吗？

[jorneyr]

把自己写的代码也像 JS minify 那样搞一下，大家一起看不懂

[Leigg]

这个没办法，以后你会经常遇到，除非老大提出来解决，否则都是看个人心情，你现在不懂哪里就问，不过最后先看完整体逻辑，再提问，自己写好注释

[xiaoxinxiaobai]

你读一遍代码给加上注释

[notejava]

可读性强的代码就是最好的注释。如果代码本身就逻辑混乱，也别指望注释了。

[notejava]

可读性强的代码就是最好的注释。如果代码本身就逻辑混乱，别指望他能写出好的注释。

[zsyld]

辣鸡代码才需要注释（狗头

[djs]

@labulaka521 悲伤

[elintwenty]

既然制定不了规范就不要管了，比起没有注释，过时的、失效的注释是更大的灾难。如果不能保证你的、甚至因你而出现的注释鲜明有效，那么还是完全没有更好。可以尝试要不要引入一些自动化的工具来建议主管去考虑

[maddot]

函数名称就是最好的注释

[zsdroid]

看了上面这么多楼的发言，感觉 jdk 特别垃圾，因为注释特别多。

[4771314]

基本的注释还是要有吧，不然谁看得懂？
代码是写给人看的，不是写给计算机看的。

[labulaka521]

@notejava 是的 但是还存在一些被重构 被迁移的字段 函数 几乎都没有注释 用了旧的函数 字段偶尔就会报错

[idoggy]

注释基本都是用来写 why 和 how 的，很少写 what 的，看事情不要二极管

[alcoholpad]

良好的函数名, 变量名 就是最好的注释, 函数尽量短小. 如果像写文章一样认真写代码, 根本不需要注释.
毕竟代码的修改会经常忘了同步注释, 更容易让人误解.

[UmiKz]

开发规范做到见名知其意，注释少些，也影响不大

[watzds]

这不是挺正常吗？

[zjsxwc]

除非复杂的业务逻辑我会先写注释后写代码做填空题，同时会引用产品经理具体需求描述的 issue id 方便后续跟进，还有这种复杂的业务由于不具备可复用性，我基本都是写在一个大方法里面。


大部分时候业务逻辑等价于 4 、5 个 sql 查询的就不写注释了，这种猜都能猜到是在干什么。

[darktutu]

我遇到过注释和代码不匹配的，更痛苦，还不如没有注释呢。

[aydd2004]

说真的 我给自己写的东西都加一堆注释

这些人哪里来的勇气

[UsherOu]

@labulaka521 代码即注释，见名知意

[darkforest8848]

@jerryrib 兄弟 bannner 能发下吗

[zhangyangkam1]

改变不了环境可以从自己做起

[faceRollingKB]

时间不够

[JamesR]

外包做的，时间不够嘛。

[ungrown]

注释其实算是个历史遗留产物
以前计算设备算力低，开发机的算力也低
自然也没有如今功能强大的 IDE 软件辅助写代码
所以那时候代码字词句能少就少尽量简洁
那么代码的含义就很难从代码本身看出来，需要注释
现如今在 IDE 的自动补全代码树监控的加持下
长名超长名蔚然成风
代码含义几乎可以完全通过合理命名来显示表达
“代码即注释”
只有很少的情况下，才不得不依靠注释进行说明，例如：
命名无法体现含义，亦或妖码怪码 bug 码不讲道理，亦或“知其然不知其所以然”的代码

[tikazyq]

这种项目，当你花了半天时间读懂的时候，需求已经变了，淡定

[jatsz]

代码不会说谎，注释会。

[hyperbin]

@djs 题主这情况多半还有拼音变量

[fhsan]

@jatsz 注释才是最坑爹的地方

[751327]

@jatsz 有时候宁愿相信代码

[jerryrib]

@darkforest8848 https://www.codepile.net/pile/Y8Qrn1D2

[ligiggy]

理清业务逻辑可以写注释，封装接口给人用要文档。但是如果每一个函数，每一个命名都要写注释，那才是最垃圾的。代码要提升的是可读性，而不是人人口中的“注释”。

[jatsz]

@fhsan
@751327

基本上问这个问题就不是代码的问题，或者说技术问题，而更多的是管理问题。用技术的方式解决管理问题其实很糟糕。
真如楼主说的，团队强制让人写注释了，谁对注释负责，谁对代码负责。

还记得《让子弹飞》中的六子么？当你真的遇到了问题哭着说：“你们看看看啊，我支持了一碗凉粉”。你会发现周边根本没人听你的。

[matrix67]

上 ci，没注释拒绝合入

[xianxiaobo]

@labulaka521 我想说的是，如果你不是领导或者老板，根本没办法。写注释确实是减少了维护成本，但是增加了开发时间啊。谁来为这部分买单呢？另外，我说的确实是解决办法，不完全算是阴阳怪气。

[sunznx]

见过 curd 还加注释的

[sunznx]

见过 curd 还加注释的

// 获取一个用户
// 删除一个用户

这种注释还不如不注释

[qiumaoyuan]

@labulaka521 注释的作用主要是说明代码为什么要这么做，而不是描述代码在做什么。

另外软件开发就是要极端。没有极端过，你根本不知道“中间”在哪里，不知道极端在哪，所谓的折衷、权衡都是在搞笑和自慰。

[fyooo]

国内大环境根本解决不了，这类需要从上至下的推动的

[casillasyi]

代码写的一塌糊涂的，需要注释才能看懂的，你以为他注释写的你能看懂吗？

[wysnylc]

@qiumaoyuan #74 学数学的时候恨不得注释多的拉满,到自己写代码就觉得注释麻烦没意义笑死了

[Still4]

@darktutu 需求变了，注释没改，我们这跟没写注释是一个原因，需求压力大，很多时候上午提需求晚上上线，谁想让后来人指着自己鼻子骂呢，时间不允许没办法，优先保证东西正常，注释都是想着后面再说，一拖就没影了

[northisland]

一行注释都没有的是垃圾；不分巨细，全注释的也是垃圾。

还是武侯祠「攻心对联」里的那一句“不审势，则宽严皆误”。

（但对于外行领导，想通过 5 分钟 code review 就深入理解我做的事情，目测领导也是垃圾。）

[lk920724]

这样想，没注释总比过期注释要好。

[sdushn]

做 cr 啊，看不懂的，格式不对的都不让合入，

[djyde]

注释不是用来解释这段代码在做什么，而是告诉后来的人为什么要写这段代码。

[paoqi2048]

楼上一堆洗的，希望你们以后的同事都不写注释哈

[haha512]

看了上面回答，应该把第一个设计代码要加注释的人拉出来痛打一顿。
v2 任何一个问题下面， 总少不了一堆的“逼王之王”，为什么呢

[pangleon]

让 AB 互相改他们之前做的大需求，然后看他们对喷

[labulaka521]

@haha512 没办法 总有人觉得我的代码很优雅 很优雅 不用注释 结果一看 是什么玩意 叠加五六层 ifelse 真逼王之王

[lululau]

业务代码不需要注释，类名和方法名就是注释，把 PRD 写写好是最重要的

[opengps]

写注释奖钱啊，很多人不写，不就是因为大部分企业都卸磨杀驴吗

[wysnylc]

@labulaka521 #86 你要保持这个心态,永远不要觉得自己优雅
优雅是别人对你的评价,不是自己觉得自己多牛逼,总有些人觉得自己写点代码就人上人了莫名其妙的优越感
不写注释的都是垃圾

[Leigg]

楼上一帮人，个个以为光看代码就看懂了，要么是真牛逼，没遇到过垃圾同事，要么是长期混迹小公司自己就从来不写注释的，别人问还怼别人的。
哪个比例更高一点？

[Huelse]

当然是能一起商量好最好

实在不行就你写的时候完全不按套路命名来写即可，注释留在自己的仓库，commit 的时候去掉注释

[zerofancy]

lint

[tony1890]

没办法。只能管好自己。虽然我跟同事说过多次，不用的代码要么注释要么删除，方法最起码说明是干嘛的，公共方法还要写入参和 returns，公共组件要写文档。balabala 一堆。
然而他们很难做到。唯一欣慰的就是提交写简短记录了。

[newmlp]

又不是不能用

[darktutu]

@Still4 是啊，所以我挺好奇的，一般项目的注释都很完善，只有我遇到的是乱糟糟的?还有就是单元测试，也是没多少或者没有，到那时看评论，大家经常都是齐备的，我也搞不明白。

[tabris17]

我只在个人项目里会尽责地写注释

[troywinter]

题外话，注释和代码有不同的目的，不存在好的代码不需要写注释的，他们的目的本来就不相同，有些简单的逻辑确实不需要注释，但大多数情况下，注释还是应该解释下这样设计的原因和用法，最好链接到设计文档。

[qiumaoyuan]

@labulaka521 也许你见过你口里描述的人，但同时你要知道这世界上真有不少人的代码是不用注释的。把无法理解的事情打个装逼的标签，把难以实现的理想当作自己不努力的借口对自己没有好处。有理就好好讲理这是程序员的基本素养，起码冰冷的机器不会照顾你的个人情绪。

[tankren]

看可读性吧

[lazydog]

不写注释看来是真的不行，我一周前的代码，今天看的时候竟然看不懂了，费了好长时间才反推回去。