找回密码
 骑士注册

QQ登录

微博登录

搜索
❏ 站外平台:

Linux中国开源社区 观点 查看内容

请注释你那该死的代码

| 2012-12-03 10:54   评论: 8 收藏: 3 分享: 1    

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

请注释你那该死的代码。

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

错误的藏身之处

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

不要偷懒

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

你是有经验的人

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

你会打字

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

你在一天天变老

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

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

 

[本文英文原文链接:Comment your damn code ]

译文:http://www.aqee.net/comment-your-damn-code/

收藏


最新评论

我也要发表评论

wangweizhu 2012-11-30 22:43 回复

毫无疑问,我也赞同作者的做法,以后吧,我会把我的注释写得更清晰、明白一些。

DeadFire 2012-12-04 11:08 回复
回复 wangweizhu 的帖子

当经历过了几次自己写的代码自己都读不懂当时为啥这样写的时候,写注释就会成为一种习惯了。

wangweizhu 2012-12-04 14:21 回复
回复 DeadFire 的帖子

其实自己写过的代码并非真的过后会读不懂,只是回头读起来会比较困难,要整理一下思路才能继续,写了注释之后会帮助我们理解当时的思路,所以读起来比较容易,当然也对其他人有很大的帮助。

DeadFire 2012-12-05 13:53 回复
回复 wangweizhu 的帖子

有很多时候我是,本来写一些特殊需求的时候,本身就已经费好大的脑子来解决了,终于解决了的时候,就完全不想再写个注释了,同时认为自己写着的印象那么深刻,应该以后不会忘记,结果到时候还是会忘记,由此看来脑子已经在退化了,哎。

wangweizhu 2012-12-07 02:20 回复
回复 DeadFire 的帖子

脑力退化是我们这些程序员的通病啊,真的不得不认老,我感觉到搞我们这行的老得特别快,特别彻底!

DeadFire 2012-12-10 14:54 回复
回复 wangweizhu 的帖子

哈哈,多吃核桃。

soli 2012-12-11 13:50 1 回复

另一个极端是过度注释。

DeadFire 2012-12-13 10:08 回复
回复 soli 的帖子

很难把握的,一旦性起,注释起来没完的。

返回顶部

分享到微信

打开微信,点击顶部的“╋”,
使用“扫一扫”将网页分享至微信。