注释是恶魔,请不要再写一行注释

你可以从你们现在项目里面随便找几处注释,看看写注释的代码是不是存在如下两种毛病之一:

  • 1. 命名不准确;
  • 2. 方法太长(超过50行)。

如果你找到的代码没有出现上面两种毛病而注释依然存在,那你再看看这个注释是否有实际意义,是不是这个注释不要也无所谓呢。

注释是恶魔

这个观点可能你第一次看到,你可能很难接受,因为写了这么多年的注释,你从未想过注释居然是恶魔,所以,你看到这个观点的时候可能就会本能的找出1000种理由反对(绝对不可能实现啊什么的),但是,这个观点并不是今天才出现,相信很多年前就有人提出,现在已被越来越多的人认可。

我第一次接受到这个观点还是从一个美国客户(十几年编程经验的技术大牛)那里,2011年,他让我们不要写注释。他当时主要意思是我们写的中式英语他猜起来太费劲,所以他后面又安慰我们说“好的代码是不需要注释的”,而我从此就将他后面那半句话奉为至宝。

注释是恶魔,它将我们的代码变得很难理解。就像本文开篇说的,你可以找找你们项目中出现注释的地方,要么命名不准确,要么方法太长。你可以随机找10处注释,看看有几处是恶魔,欢迎贴到评论中。

举一个以前项目中的例子吧,命名不准确的例子:

在这个例子中,其实将”is”换成”can”就不需要注释了。

写注释让代码更难读。

首先,如果一个程序员可以随便写注释,那么他对命名准确性和方法长度的控制就不会那么在意,写代码更随意,代码质量比不能写注释的程序员更大几率低下。

其次,代码注释只是在写代码的时候提供说明,如果读代码都依靠注释的话,那一个类被另一个类引用来引用去的就根本没法阅读了。

所以,“写注释是为了让代码更易读”本身就是站不住脚的。

不写一行注释?根本就做不到!

这句话可能从你阅读本文开始在心里面重复了无数遍,这也是大多数人的心声。

其实前面说的,写注释让代码更难读的观点很多朋友从内心上是认可的。因为确实没有办法啊,有的方法业务逻辑复杂,不知不觉方法已上百行,有的命名还是中西结合的,不写注释自己第二天就读不懂了。所以,真是纠结,内心承受百般折磨。

写到这里,突然想起在园子里看到的一个笑话,说一个公司的产品每年都在更新换代,因为每年新招的程序员都要把程序重新写一遍。

“零注释”根本做不到?如果你丛刻开始怀疑自己的这个观点,那你就可能做得到。

如何做到不写一行注释

  • 1. 从现在开始,强迫自己不要写注释。
  • 2. 控制每个方法不超过50行,用方法定义来描述方法的实现逻辑。
  • 3. 变量命名不要太过随便。

本文想要告诉大家的是,零注释一点都不难。我们团队大约从2012年开始全面执行零注释,后面经历2个产品项目,多个外包项目,积累的经验越来越多,获得的质量效果越来越好,零注释越来越深入人心。

零注释这个编码规则也是我们团队近些年质量建设非常重要的里程碑之一,再此分享给大家。如果能够影响你一点点,那都足够了。

附2个我们的代码片段

虽没有注释,大家不妨猜猜这两个方法做什么用的。

1. 查询的例子

2. 更新的例子

3 7 收藏 23 评论

相关文章

可能感兴趣的话题



直接登录
最新评论
  • 讲道理的话我写注释只是为了理清自己的思路,把一步步做什么先写好,再开始写代码

  • 消失的有希酱   2016/02/03

    参考的文档 dev design 这些还是要写到注释里去的...

  • 对我来说,注释更像一个框架,而不是解释说明

  • 辰辉   2016/02/03

    恩,加注释还不如把被注释的块重构到函数里来的清晰,我的代码就没有注释,不过都是个人代码。不过个人觉得,团队开发中暴露给其他人的代码还是得有注释,比如接口什么的,不过这一般是架构时要干的事

  • sender_is_sender 高级打杂 2016/02/04

    明显就是一个只适合楼主团队的做法。不具备普适性。

  • 嘀咕 java,python,前端 2016/02/05

    去年在博客园看到这这篇博客,大概有10页评论,清一色就4个字:博主SB

  • 令仔很忙 高级Java工程师 2016/02/05

    我觉得写注释不一定是去解释你写的代码,可以是你构思的过程!

  • sender_is_sender 高级打杂 2016/02/05

    我突然醒觉,此文的博主必定是几年来都从来没有写过一次像样的算法,所以才能零注释完全靠代码本身去解析逻辑。

  • 暴王 .net 开发 2016/02/05

    ///
    /// 管理员是否可以审核该申请
    ///
    public bool IsAudit { get; set; }

    不写注释我连这是啥意思都不明白了。

  • PunCha 程序员 2016/02/05

    第二个例子,根本就是没有注释的烂代码!充斥着:
    1. 合法性检查
    2. 职责不明,竟然向数据库提交了2条记录。
    3. 逻辑复杂,比如 totalPendings, openId使用逗号分隔的。
    。。。。

  • jason 在校 2016/02/05

    个人代码可以不需要注释,团队开发,简单的业务逻辑,比如单表的增删改查可以不需要注释。如果涉及到复杂的业务逻辑或者算法的时候,不写注释……也可以,后期维护的时候再花个几天时间来看代码,搞清这块大概的逻辑,然后整个人凌乱了……模块之间的调用,如果没有注释的话对于新手或者维护的人来说,那是绝对不能忍受的。写代码得意识到:1.这段代码不是只写给我看的;2.别人的思维模式和思维水平可能没我好(他是SB),可能比我好(在别人眼里我是SB);3.写注释就是为了方便SB理解,方便NB修改。

  • 不是不要写注释,而是要把注释写好,逻辑改了之后注释要同步修改,优秀的开源框架哪个不是有丰富清晰的注释?

  • 好的代码是不需要注释的!!!
    没有注释不能说明你的代码足够好!有注释说明你的代码一定不够好,还需要不断的去重构!!!
    可以这样理解吧

  • 写注释其实是一个好的习惯,但是在更改代码时相应的也需要更改注释,这个是尤其重要的,否则其他人看到你的注释和你的代码不一致时,就很困惑;注释一般用英文比较好,由于字符编码的问题,如果用中文可能会乱码,建议尽量使用英文

  • snack java 开发 2016/02/26

    呵呵,不写注释?特么在我手下我特么打死他

  • Jadedrip   2016/02/26

    看着大段的驼峰就眼晕。喜欢读这样代码而不是注释的人,都是奇葩啊。

  • Erwin   2016/04/03

    注释看不懂,只能说明注释的质量比较低,不能说明注释没用,好的修饰能降低维护成本g

  • 无痕 软件工程师 2016/04/03

    不完全同意文章的观点。不能完全否定注释的作用。不写注释和满篇都是注释是两个极端,都不可取,其实最终要的是注释要合理,恰当,不能误导后面的人。

  • 注释的关键是对复杂逻辑的描述,以及特殊代码用法的说明等等,以达到增强代码可读性的作用。如果一段注释写了等于没写,那完全就是画蛇添足。

  • Albert__Sun Stu 2016/04/05

    写得好的代码,清晰易懂,可以不用注释。写的烂还不让写注释?自欺欺人嘛!

  • 煜-月光独奏 全栈工程师 2016/04/06

    通常来说,能用一行注释的,大致用代码就可以解释清楚,关键是命名要恰当,符合规范。比如至少交代该函数的用意等

  • 我觉得注释就是思考的过程,虽然写的内容不一定适合每个人的口味

  • 好,按照你的说法,我看你的第二个例子,我必须读代码才知道你添加了两条记录,那么问题来了,维护的人真的有那么多的时间来跟你的代码吗? 注释大多数情况下是为了方便阅读代码,往往在维护过程中尤为重要!

跳到底部
返回顶部