“注释越多代码越烂”，请注意，这绝对不是哗众取宠。
著名的恩格尔系数是怎么表述的？
“用于吃的比例越高说明生活越贫困”
我们第一次见到这句话的时候不也是同样地惊讶，不可理解。
换个角度想想，的确如此，那我的程序不写一行注释，不就变成不烂的代码了吗？哦，如果你生活在贫困线上，即使你每天只吃一个馒头，余下的钱都用来参观展览、听音乐会……，那么你富有了吗？不，你依然是贫困的，而且是面黄肌瘦的。
那这句话真正的意义何在？或者说对我们有什么用处？
下面我们就讨论一下，首先是个引子
有人看了我的代码，抱怨我的注释太少，然后告诉我注释应该占源文件的一半，甚至是三分之二。
实在是令我吃惊，真的需要这么多的注释吗？去参观他们的代码，的确，注释很多，不可否认，其中有些对于理程序确实是不可或缺的，但更多的呢，是下面这样的：
/*******************************************************
* 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的基本用法？唉！到底有谁见过电路原理图上有那么多的注释？我们学电路都是先学各种各样的单元电路，在了解了它们的具体功能之后再学习由这些单元电路组成的更大规模的电路，看电路图的时候你要是问出像“这个怎么能实现电流放大？”这样的问题，相信四座都会无语的，为什么？因为它就是个放大电路啊！用得着解释吗？如果真的需要解释，去看《模拟电路》好了。
除了这些，还有什么东西使得注释如此泛滥呢？
那就是
扭曲的设计
这种设计虽然也能够解决问题，但是它有悖于一个正常人的思考过程，所以它需要代码中的大量注释，来修正人们简单而直接的想法，我最怕看的就是这种代码，我怕自己给它们教坏了，一个良好的设计必然是易于理解的，易于理解的设计自然无需太多的注释，最可悲的事情就是因为时间的关系，你没有办法去重写它们，只能按照你所憎恶的方式行事。 
|
本类阅读TOP10