❏ 站外平台:

让那些无用代码注释见鬼去

| 2014-12-16 13:58   评论: 37 分享: 45    

注释简单代码会干扰对重要注释的理解。程序开发者最好能用最精要的注释来解释重点代码。

举个例子,你打开一个电箱,里面有几百根电线,蒙了吧。再一看,每根电线上面都有一个整洁的小标签。真是谢天谢地啊!但是,当你一个个去翻看标签的时候,见鬼的,几乎所有的标签都是空白的!

7086_13017491096X8d

然后,在你花了整整一个小时去浏览每一个小标签之后,终于给你找到12条有用的信息,真心喜大普奔!当然,希望在你头脑一片混乱的时候得出的结果仍然是正确的,没有遗漏,呵呵呵。

当我需要研究代码的时候看到到处都是垃圾注释,唉,我的感觉就和上面在那么多标签里面找有用的一样。见鬼的,想从一大堆垃圾注释里确定哪个有用简直就像大海捞针!

说一个常用的开源项目,里面都是这些垃圾注释:

/**
* __construct function.
*
* @access public
* @return void
*/
public function __construct() {

…
}

再来一个:

/**
* Constructor
*/
public function __construct() {
…
}

还有一个:

// Convert float to string
$value = float_to_string( $value );

这些注释就跟电箱里的空白标签一样,明晃晃的摆在那里,增加干扰还降低注释的可用性。看到这样的注释,怪不得那些可怜的开发人员要废寝忘食了。

我敢肯定,那个把空白标签贴在每根电线上的电工自认为这是一个特棒的主意,他帮助了那些在他后面来的人:他们有什么想写的,只要在这些已经贴好的标签上面写就可以了。当然也有可能他本来打算自己填好所有标签。撇开他的好意不说,这样做的结果真心是糟透了,还不如只贴那有用的12张呢!

在编程的时候,开发人员经常被告知要注释,但是他们中很少有人知道怎样注释才好。所以开发人员注释代码的时候,并不是因为有必要,而是因为他们觉得这是义务。开发人员认为如果在代码中多多注释,能表现他们工作能力。

见鬼的,这也不知道是哪门子的理论。我最厌烦每隔几行代码就有注释,而实际上却屁用没有。注释的作用绝对不是为了纯粹炫耀我们是“不明觉厉”的程序员,而是为了重点记录我们搞这些代码的原因。这样一来,那些垃圾注释就能滚蛋了。看下面的例子:

// We need to account for product price changes,
// so we get the price of the product when each order occurred
$order_prices = $this->get_order_prices();

说说我的做法吧,当我考虑是否要写注释的时候,我就问自己:如果以后回过头来看这些代码,我能不能一下子明白当初为什么要这样写?如果以后我会非常感谢这些注释,那么想也不用想,果断写上注释。否则,就让那些垃圾注释见鬼去吧。



最新评论

[1]
来自 - 上海 的 Chrome/Linux 用户 发表于 2014-12-18 15:58 的评论:
不太认同部分观点,很多注释是用来自动生成api文档的,也许在代码里有部分注释可有可无,但是对比要另外撰写文档来说,通过注释自动生成减少了很多工作量,维护也更方便
linux 2014-12-18 21:12 1 回复
嗯,是的,其实我看本文只是代表了一种态度。
_冇木偶娃娃_ 2014-12-17 19:05 1 回复
亲,帮我去网络机柜找下XXX的网线,我们忘写标签了,哦,对了,寻线仪好像没电了!
微博评论 2014-12-17 12:03 回复
→_→//@Linux中国:→_→//@小新de蜡笔_: 曾经一个在公司8年多的哥们开会时说:从我来的时候这段代码就是注释掉的,没人知道是干啥的,也没人敢删→_→//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 11:33 回复
从来不爱写注释,是不是很不合格![嘘]
微博评论 2014-12-17 11:33 回复
初学者经常把原来的复制一份注释掉,然后开始改 //@Linux中国:→_→//@小新de蜡笔_: 曾经一个在公司8年多的哥们开会时说:从我来的时候这段代码就是注释掉的,没人知道是干啥的,也没人敢删→_→//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来
微博评论 2014-12-17 11:33 3 回复
你现在看不懂的代码,都是那些曾经你认为以后看一眼就一定能懂的。
微博评论 2014-12-17 11:33 回复
→_→ //@小新de蜡笔_: 曾经一个在公司8年多的哥们开会时说:从我来的时候这段代码就是注释掉的,没人知道是干啥的,也没人敢删→_→//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 11:03 1 回复
⇉⇉//@Linux中国: →_→//@小新de蜡笔_: 曾经一个在公司8年多的哥们开会时说:从我来的时候这段代码就是注释掉的,没人知道是干啥的,也没人敢删→_→//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 11:03 回复
深有体会,受教了!很赞~[哈哈]//@Linux中国: →_→//@小新de蜡笔_: 曾经一个在公司8年多的哥们开会时说:从我来的时候这段代码就是注释掉的,没人知道是干啥的,也没人敢删→_→//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么
微博评论 2014-12-17 10:33 回复
想着总有一天会用上[doge]//@Linux中国:→_→//@小新de蜡笔_: 曾经一个在公司8年多的哥们开会时说:从我来的时候这段代码就是注释掉的,没人知道是干啥的,也没人敢删→_→//@Linux中国: 这我也是啊 →→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么久而久之,它们就成了注释。
微博评论 2014-12-17 10:03 回复
→_→//@Linux中国: →_→//@小新de蜡笔_: 曾经一个在公司8年多的哥们开会时说:从我来的时候这段代码就是注释掉的,没人知道是干啥的,也没人敢删→_→//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 10:03 回复
额 中枪//@Linux中国: →_→//@小新de蜡笔_: 曾经一个在公司8年多的哥们开会时说:从我来的时候这段代码就是注释掉的,没人知道是干啥的,也没人敢删→_→//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 10:03 1 回复
→_→//@小新de蜡笔_: 曾经一个在公司8年多的哥们开会时说:从我来的时候这段代码就是注释掉的,没人知道是干啥的,也没人敢删→_→//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
[1]
绿色圣光 发表于 2014-12-17 08:22 的评论:
我有不少同事喜欢写这样的注释:
//某年某月末日某人修改
linux 2014-12-17 09:30 1 回复
ME TOO
微博评论 2014-12-17 04:33 1 回复
我也是→_→//@Linux中国:这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 03:03 1 回复
对对对,做ppt的时候也是 = =b//@逗比大懒猪: 我也是[笑cry]//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 03:03 回复
我也是[笑cry]//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 02:03 1 回复
最右→_→//@Linux中国:这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 01:03 1 回复
[笑cry][哈哈][哈哈]//@Linux中国:这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 01:03 回复
[泪流满面]+1//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 01:03 回复
某方案商的SDK,大片的注释代码看的心烦,怒砍之后再开发,我这暴脾气。。。//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 01:03 1 回复
记得以前有个老头墙裂呼吁过,要把语文作为大学所以专业的基础课。[挖鼻屎]//@Linux中国:这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 01:03 9 回复
就这样把我想说的话说出来了,以后人家怎么见人。注释的目的只有一个:以后看起来方便//@Linux中国:这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 01:03 回复
同意最右//@Linux中国:这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 00:33 1 回复
[嘻嘻]读没有注释的代码,读着读着就进入了陷入了深深的回忆...... //@Linux中国:这,我也是啊~~ →_→ //@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 00:33 1 回复
曾经一个在公司8年多的哥们开会时说:从我来的时候这段代码就是注释掉的,没人知道是干啥的,也没人敢删→_→//@Linux中国: 这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-17 00:33 1 回复
微博评论 2014-12-17 00:33 回复
这,我也是啊~~ →_→//@血色又残阳:一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-16 20:33 回复
一般不是都把那些不舍得扔又没什么用的代码注释起来么。。。久而久之,它们就成了注释。
微博评论 2014-12-16 20:03 1 回复
哦艹,类似int var = /*test_var*/ - var2;这样的注释我都见过。符号“-”的位置简直风骚极了,你都不知道本意究竟是符号还是减号 //@Linux中国:→_→ //@shengwenbo:喜欢在注释之间插入代码[嘻嘻]@欣然Sherry
微博评论 2014-12-16 20:03 回复
→_→//@shengwenbo:喜欢在注释之间插入代码[嘻嘻]@欣然Sherry
微博评论 2014-12-16 16:33 1 回复
@我的印象笔记
微博评论 2014-12-16 16:03 回复
喜欢在注释之间插入代码[嘻嘻]@欣然Sherry
微博评论 2014-12-16 14:58 7 回复
Documentation is like sex: when it's good, it's very, very good; and when it's bad, it's still better than nothing. --Dick Brandon
微博评论 2014-12-16 14:17 1 回复
众说纷纭 喜欢全注释

返回顶部

分享到微信

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