请注释你那该死的代码

我站出来就是为了要说一句:

请注释你那该死的代码。

每次我遇到一个程序员——有时是相当高水的——总发现他会认为:你并不需要给你的代码加注释。我要说,这就是胡说八道。我很长时间以来一直这么表达。问题是,让事情改变要比你想象的难。虽然我们正处在努力编写那些讨厌的代码、准备发布一些会令人惊叹的新东西的紧要关头,我们仍然几乎注释所有的东西。没有任何借口不去做这些事情。每隔3到7行代码,你就能看到有长篇的社论发表。有时,几百行代码里,你就能找到一个很好的笑话。

错误的藏身之处

看,一个是你想要的,一个是你实现的。你的bug就在这两者之间。如果写了注释,你就是在告诉我你想要的。而你的代码中告诉我你是如何去做的。程序的缺陷要么存在于你想要的想法中,要么,需求是对的,而你的代码有问题。请帮助我,让我知道究竟是哪个错了。

不要偷懒

一个常见的反对声音是:我听说,注释经常会过期,因为代码会经常更新,而注释不会。你不更新注释吗?你的同事也不?不要偷懒,不要养成一个让人认为偷点儿懒无所谓的文化氛围。告诉同事你是如何一丝不苟的注释程序的,让他们知道你也希望他们这样去做。说不注释是因为怕某人或某些地方在将来会造成你的错误,这只是在找借口。

你是有经验的人

人本无知,这很自然,但你是有经验的人。因此,你有义务教育那些需要学习的人。你的注释会指导那些正在阅读你的代码的人。告诉他们为什么在这里要用Tuple数据结构,而不是用其它的(更好的做法是附加一个stack overflow或dotnetperls上的链接 … 你完全可以做到这些,不是吗?)你在这走了一个什么捷径?如果不走捷径你就不能按时发布,所以,告诉这些新手你遇到的特殊情况。否则的话,最终你的不好的代码将会被四处拷贝,四处散播。看!你写的烂代码变成了公司的程序模板!完全没有注释!

你会打字

我的招聘过程有一部分是白板编程,一部分是键盘编程。所有好的程序员都是打字高手。就说你每分钟能打出40-60词。那请你告诉我,为什么在你机枪扫射似的编写代码时不加上注释呢?当然,你可以花30秒时间告诉我,代码写的这样一团糟是因为搞业务的那个家伙需要程序在本周发布而换回不菲的7.5万美元。可是下个月呢?这些代码不要了?封存到石头里了?我知道这些代码是在干什么。但请告诉我你的意图

你在一天天变老

听我说,我编程已经很久了,也许早在你上中学之前。我仍然在编程,我仍然喜欢编程。有朝一日,你也会变的跟我一样老。如果你到了像我一样(那时我已经没有能力再教育你),那时,有太多的层,有太多的抽象,有太多的技术架构,你无法完全记住。你的注释就能出来指导你。它们会告诉你,6个月前,你是用这种方法、这种模式实现的,而且这样做只是为了炫耀。如果你是一个真正优秀——并且仍然在做编程的程序员——你会认识到,这些代码写的很烂,你现在需要以不同的方式重新实现它。而你仍然有你的注释来让你回忆起当时的想法和为什么这样做。

所以,请注释你那该死的代码。

[英文原文:Comment your damn code ]
分享这篇文章:

30 Responses to 请注释你那该死的代码

  1. anony says:

    别听这个蠢货胡扯。应该尽量在没有注释的情况下让别人能看懂你的代码。吧注释代码看作是无能的表现才是正确的方向,当然,前天是必须能使别人能看懂你的代码。

  2. Null says:

    如果你认为这段代码只有神才能一眼看穿,那就注释吧.

    某人曾经讲过,彪悍的source code不需要comment.

  3. amos says:

    注释代码的时候我要花时间,有时候项目周期很紧。代码全是手敲,这全归功于我们都是新手。虽然我也提过建议,并共享过很多自己认为还不错的代码。
    结果。我们还是继续手敲,项目周期还是紧,有些注释就省了。
    没注释代码别人要花更多的时间来看我的代码。因为都是新手。
    其实楼上的说的很好,我是个烂程序员。
    我们注释代码。只是不想让和我们一样的新手看不懂。

  4. David says:

    好的代码本身就是注释,但是你写出的是好的代码吗?所以请注释你那该死的代码。

  5. lys says:

    你以为加了注释就能看懂吗?扯!你以为你从注释中看到的就是写注释的人想表达的?扯!

  6. 依云 says:

    我见过需要看代码才能明白的注释 😀

  7. pz says:

    我的代码不开源、不需要写注释、再过十年、我自己也能看懂,哈哈

  8. @earth says:

    这篇文章有潜力入选十大评论。
    为什么不写注释呢?为什么要花时间写注释呢?这是一个问题。
    作为一个不爱注释的码民,我的做法是在必要的地方写下合适的注释,如作者所说,“告诉他们为什么在这里要用Tuple数据结构,而不是用其它的(更好的做法是附加一个stack overflow或dotnetperls上的链接)”。

  9. adsf says:

    Clean Code. 解决问题不要走极端。注释是必要的。

  10. literate programming says:

    这个家伙说了一通废话。要是他真的那么看重代码注释,为啥不用 knuth 发明的文学编程呢?

  11. 王超 says:

    注释大多时候是为了解释业务,为什么要这么写。。技术的话大家都差不多。。

  12. 独行猫儿 says:

    看完文章之后我觉得文章写的不错,赞一个。
    看完评论之后我觉得,浮躁的coder也真jb多。
    作为一个测试工程师,我已经看多了各种产品以及各种代码。
    你们的代码,就像是读了一篇几千行的英文文献似的,真的,可能里面语法没错,但是核心思想或者实现方式或者功能定义就有问题(参见大家身边的各种垃圾电子产品)
    注释并不是让你用人类看的懂的语言去翻译计算机代码语言,而是要写你打算如何实现功能,为什么要以此方式实现这个功能,以及,这堆滥造的代码是谁写的。

    以上,个人观点,勿乱喷。

  13. cxh116 says:

    错了,你需要的不是注释,而是测试

  14. Jerry says:

    能用一句话就概括一个方法或者一个类的功能的注释为什么不去做呢?如果别人在没注释的情况下需要花十分钟来明白你写的代码含义,而一句话的注释只需要十秒钟。这个时间成本你们都有考虑过吗?个人的项目无可厚非,反正是你自己看,但在一个团队项目中,为团队中的其他人提供便利才能凸显你的价值。请不要为自己的懒惰和自私找借口。我见过无数的人说自己的项目以后不会有人接手继续开发,但结果其实往往公司不会那么轻易就把一个项目cancel掉,即使它的代码有够烂。

    • Yonghang Jiang says:

      能用一句话说清楚的信息就可以塞进函数名里了。建立一个子函数,用函数名描述你想做什么,然后调用这个函数。
      不过话说回来,有些时候你确实需要注释一些奇怪的代码,原因是你一时找不到清晰的实现方式。

  15. 铁坑 says:

    有些人不要走极端,必要的注释很有用。代码的后期维护往往都不是开发者本人,而接手人员的能力参差不齐,想让别人尽量少的破坏你的源码,你就得想方设法让别人(想象成低能儿吧)明白你的代码,注释是一个有效的辅助手段。当别人阅读你的代码需要10分钟才能明白你的原意时,为何不试图加上注释让别人能在1分钟内就明白呢?

  16. Gabriel says:

    看到好多彪悍的人声称自己十分牛逼。。他们的代码都是十分漂亮的。
    那么,请即刻由自己做起,抛弃掉手边的一切文档吧。再也不要看 Java 的文档,不要再登录
    MSDN,不要再接触 C++ reference。。。

    至少别人不单止有注释,还有文档呢。。估计他们比以上的这群作者都要牛逼。。

  17. CESC  这篇文章, 并对这篇文章的反应是赞一个
  18. AndyAo says:

    阅读代码时可能有这些信息对理解有帮助

    1. 读者本身的知识
    2. 代码本身
    3. 对代码的注释
    4. 文档
    5. 测试

    这是很多因素互动的结果,不像是简单能下结论的事情。

    考虑的时候应该从不同角度来进行,如果较真点,可以用科学手段严肃研究下。

  19. AndyAO says:

    对于我来说,更喜欢用文档而不是注释来解释设计的理念。
    文档是HTML,看起来比注释更容易更方便,而且更新文档会更庄重,因为注释除了给别人看,还会有很多奇奇怪怪的用途,分开会更好。

发表评论

电子邮件地址不会被公开。 必填项已用*标注

This site uses Akismet to reduce spam. Learn how your comment data is processed.