注释越多代码越烂——这绝不是哗众取宠

原创 2004年09月07日 15:49:00

“注释越多代码越烂”,请注意,这绝对不是哗众取宠。
著名的恩格尔系数是怎么表述的?
“用于吃的比例越高说明生活越贫困”
我们第一次见到这句话的时候不也是同样地惊讶,不可理解。
换个角度想想,的确如此,那我的程序不写一行注释,不就变成不烂的代码了吗?哦,如果你生活在贫困线上,即使你每天只吃一个馒头,余下的钱都用来参观展览、听音乐会……,那么你富有了吗?不,你依然是贫困的,而且是面黄肌瘦的。

那这句话真正的意义何在?或者说对我们有什么用处?
下面我们就讨论一下,首先是个引子

有人看了我的代码,抱怨我的注释太少,然后告诉我注释应该占源文件的一半,甚至是三分之二。

实在是令我吃惊,真的需要这么多的注释吗?去参观他们的代码,的确,注释很多,不可否认,其中有些对于理程序确实是不可或缺的,但更多的呢,是下面这样的:
/*******************************************************
* FUNCTION NAME: iPrSendDataByCom
* DESCRIPTION:
*   Send Data By Com Device
*
* AUTHOR: 张三
*
* INPUTS:
*  
*
* RETURN:
*   无
*
* HISTORY: <函数创建及修改的历史记录>
*   NAME  |    DATE   | REMARKS
*--------------------------------------------------------
*   张三  | 2003-8-14 | Created initial version 1.0
*
********************************************************/
int iPrSendDataByCom( OINT  iComPort,  unsigned char *pbuf,  unsigned long size )
{

我实在是看不出来这将近20行的注释有多大用处
函数名,函数定义中就有,用得着再重复一遍吗?
最重要的功能描述,简单地只比函数名多三个字母;
输入,对三个参数的意义未有任何解释,还写着干吗?
返回值,竟然和函数定义牛头不对马嘴;
就只有作者信息和修改纪录有那么一点点微不足道的用处了,可这用得着给每个函数都顶着这样一顶大帽子吗?还有那一行行的****,你写不了几个字它们就会因为不能自动换行而变得丑陋不堪。
很明显,形式主义!不过考虑到这是公司里的代码,要应付某些人的要求,尚可理解。
但是,有些东西我就实在是无法理解了,最常见的一些idiom都看不懂吗?如何给一个回调函数传递参数还要我在旁边加上一堆注释吗?难道还要我在源文件中解释semphore的基本用法?唉!到底有谁见过电路原理图上有那么多的注释?我们学电路都是先学各种各样的单元电路,在了解了它们的具体功能之后再学习由这些单元电路组成的更大规模的电路,看电路图的时候你要是问出像“这个怎么能实现电流放大?”这样的问题,相信四座都会无语的,为什么?因为它就是个放大电路啊!用得着解释吗?如果真的需要解释,去看《模拟电路》好了。
除了这些,还有什么东西使得注释如此泛滥呢?
那就是
扭曲的设计
这种设计虽然也能够解决问题,但是它有悖于一个正常人的思考过程,所以它需要代码中的大量注释,来修正人们简单而直接的想法,我最怕看的就是这种代码,我怕自己给它们教坏了,一个良好的设计必然是易于理解的,易于理解的设计自然无需太多的注释,最可悲的事情就是因为时间的关系,你没有办法去重写它们,只能按照你所憎恶的方式行事。

迅雷越來越烂了

我記得我是2002年就開始使用迅雷了,用到現在才勉勉強強29級中將而已.最初的時候只是用他的多下載點來下載軟件,確實那時候的迅雷的確很棒,比起螞蟻,快車等速度好很多.當然了這是需要付出代價的,那就是我...
  • sibang
  • sibang
  • 2014年08月21日 16:42
  • 539

马云最新撰文:公司假口号越多 员工士气越低落

原标题:马云最新撰文:呵呵写了这么多,只希望对有用的用 阿里巴巴集团董事局主席马云在“来往”官方扎堆“江湖情”中就企业文化建设与广大创业者交流。 以下为全文: 今天,我想和大...
  • deerleaper
  • deerleaper
  • 2014年01月22日 15:47
  • 481

房价去库存,越去越多

由于从今年上半年起,国内三四线城市的房地产市场开始火爆,因此今年我到三四线城市的机会也多以起来。今年政府对三四线城市房地产市场的政策是,“因城施策”的房地产市场去库存。即是要通过让2015年下半年起导...
  • bat1992
  • bat1992
  • 2017年06月28日 14:31
  • 143

关于烂代码的那些事(上)

1.摘要 最近写了不少代码,review了不少代码,也做了不少重构,总之是对着烂代码工作了几周。为了抒发一下这几周里好几次到达崩溃边缘的情绪,我决定写一篇文章谈一谈烂代码的那些事。 这里是上篇,...
  • jt521xlg
  • jt521xlg
  • 2015年08月11日 10:34
  • 1255

关于烂代码的那些事

http://kb.cnblogs.com/page/526768/ ============上篇============   1. 摘要   最近写了不少代码,review了不少代码,也做了不少重构...
  • bluejoe2000
  • bluejoe2000
  • 2016年03月14日 12:10
  • 1705

读《驯服烂代码——在编程操练中悟道》

读《驯服烂代码——在编程操练中悟道》 第2章 按图索骥地编写代码 第4章 调试一下 第5章 用TDD重做编程操练题目 第6章 消除假数据所带来的重复代码 第8章 嗅出代码腐臭和新的测试点 第9章 测试...
  • q547550831
  • q547550831
  • 2016年06月26日 19:59
  • 2848

文摘:你越对, 得罪的人越多!

中国人求的是圆满,绝对不是对错。实际上这是最难做到的。中国人最讨厌没是没非的人,但是中国人最不喜欢是非分明的人。凡是是非分明的人,人缘都不好,事情都办不通。 我们是要求很高的民族,我们要在圆满...
  • zjc314
  • zjc314
  • 2017年02月19日 10:46
  • 421

为什么你学的越多,越没法行动?

行动,只有行动能带来生活的改变,这个不用说了。 我在职业发展课上讲了十二小时,最后让大家写这个课程你印象最深的一句话。 很多人写:“如果不行动,听多少课都是这个怂样。” 如果只能记得一句,那这一...
  • tomotayuki
  • tomotayuki
  • 2015年07月13日 11:12
  • 351

知道得越多,越难改变观点

好,人们会倾向于关注与自己相信的观点一致的信息,而且也会对传递信息的来源做出选择。似乎情况一直如此,对吧?也许是的,但如今这个问题无疑变得更严峻了,因为人们浏览信息的方式发生了变化——人们会通过fac...
  • asasvasv
  • asasvasv
  • 2014年06月23日 12:02
  • 284

39岁程序员的困惑:知道越多编程越…

Zilk1988 年 14 岁时就开始编程,此后尝试过几种职业,最终还是在 1997 年决定成为职业程序员(又称码农),现在已经 39 岁,对此选择依然无怨无悔。   但是后来他发现一个问题,自己的...
  • arvin0
  • arvin0
  • 2014年07月29日 10:37
  • 251
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:注释越多代码越烂——这绝不是哗众取宠
举报原因:
原因补充:

(最多只允许输入30个字)