分享
 
 
 

关于脚本中注释的五点建议

王朝other·作者佚名  2006-11-24
窄屏简体版  字體: |||超大  

当你学习某代码技术已经基本入门以后,自然会注意到提高代码质量的重要性,而书写注释则是提高代码质量的第一关——可能也是最容易的一关。以下是我总结的关于书写注释的一些建议!

一、切勿为了注释而注释!

为代码添加注释的最主要目的是提高代码可读性,但这里面还有一个心态问题:如果你认为,写了注释,就可以提高代码质量,就可以证明实力,那就错了,事情并没有那么简单。

相信一定有人在写注释的时候,没有把握正确的心态,这就导致写出来的注释往往不合时宜。什么是不合时宜的注释?我就写过这样的注释:

……

'打开记录集,记录Orders表所有数据

objRS.Open "SELECT * FROM Orders",objConn,1,1

……

objRS.Close '关闭记录集

Set objRS=Nothing '释放记录集对象

……

明白了吧?这就是不合时宜的注释的情形之一:形式化的注释,往往会成为代码的累赘,甚至无法突出真正需要注释的地方,降低了代码的可读性。

这都是心态没有把握好的原因。如果能正确把握心态,就会把心思放到提高代码可读性上,而不是放到写注释上了!写注释只是提高代码可读性的手段之一,而且写注释也是要讲技巧和效率的。下面将对此进行讨论。

二、废话连篇的注释不是好注释!

在我看来,优秀的命名规范和代码格式往往比注释更能提高代码可读性。命名规范可以说明代码元素的作用,而代码格式则能使编程思路更清晰——不过很遗憾,它们无论如何都跳不出代码的圈圈,对代码的描述能力并不强,所以我们还是要依靠注释。

因此,我们应该先在命名规范和代码格式两个方面严格要求自己,然后再以注释为辅助来描述代码。——请不要怀疑,你读代码的时候是先看代码还是先看注释?一般的情况是,代码能明确说明的问题往往就不需要看注释了,比如上面第一点里写出的那些垃圾注释,没人会把它们当回事的(但被当作入门教程中的示例还不错)。当然,也有例外,以注释为代码主要描述手段的情况在第三点讨论。

什么样的注释才是合时宜的呢?在适当的地方,以适当的篇幅写出来的注释就是合时宜的。我不能给你更具体的答案,但方向已经指明了,你需要做的就是思考、参考、再思考……总之,让注释也和代码一样简单、优雅而又有效就是目标,这样的代码才能达到提高代码可读性的效果!

仅仅是合时宜还不够,如果注释含糊不清,仍然不是好注释!所以,让注释更准确地描述代码同样重要,特别是对函数/过程、技巧性质的代码段等。以昨天那篇文章(你抄近道了吗?——源自两个VBS过程的感慨)中提到的两个过程之一——GetRandom——为例,我为其作用的描述是:返回从源数组中随机抽取指定数目的位置不重复元素组成的新数组。如果让你描述它的作用,你会如何描述?请不要误会,我可不是在自卖自夸,我只是取了一个离自己最近的例子而已。

总之,好的注释,要合时宜,还要准确有效!否则不如不写。

三、外部文档往往比内部注释更有效!

你也许会奇怪,我上面强调了函数/过程和技巧性质的代码段的注释要准确,为什么我没有提到对类的注释呢?个人以为,如果程序广泛采用了面向(或者基于)对象的设计方法,对类的注释应该从长计议。情况之一是,如果类需要封装,那注释也只在设计时有效,对提高代码可读性的意义不大;情况之二是,类的设计和使用应该宏观把握,而代码中的注释往往是微观的描述,很难达到宏观描述的效果——比如许多用图才好描述的类关系,注释的效果就不好。

这个时候,我们就需要有外部文档了!不要问我什么是外部文档,如何写外部文档。总之,一切为提高代码可读性服务,做你能做的一切。

还有一个问题要说,到底该在什么时候写注释和文档呢?有些人是先把代码写好,再趁着自己没有淡忘之前把注释补上;有些人先写好设计草案,然后再开始写代码……其实没有对错,达到目的就好。——注意,理性统筹的正规项目工程开发不在讨论范围内,这种开发要考虑的因素太多了,不能那么随意的。

四、尽量避免客户端注释!

客户端注释的唯一缺点应该是增加I/O压力吧?大家可以算一算,如果为HTML和客户端脚本添加注释,主观估计将为每页增加1K字节,现在剩下的就是估计页访问量了……

为什么要为客户端脚本和HTML添加注释呢?特别是为HTML添加注释更是难以理解——也可能是我没见识吧,呵呵。标准化的B/S客户端设计讲究结构、呈现、行为的分离,我想这是对客户端代码最好的注释吧?

五、常审视和改善以前代码中的注释!

写注释很大程度上也是为了防止自己以后读到这些代码的时候也不明其意,所以,如果能经常审视和改善以前代码中的注释……呵呵,还是不多说了吧,相信大家用膝盖想也能明白其中的好处。——怎么感觉我的文章都是虎头蛇尾?

最后,祝所有专情的人好运!

 
 
 
免责声明:本文为网络用户发布,其观点仅代表作者个人观点,与本站无关,本站仅提供信息存储服务。文中陈述内容未经本站证实,其真实性、完整性、及时性本站不作任何保证或承诺,请读者仅作参考,并请自行核实相关内容。
2023年上半年GDP全球前十五强
 百态   2023-10-24
美众议院议长启动对拜登的弹劾调查
 百态   2023-09-13
上海、济南、武汉等多地出现不明坠落物
 探索   2023-09-06
印度或要将国名改为“巴拉特”
 百态   2023-09-06
男子为女友送行,买票不登机被捕
 百态   2023-08-20
手机地震预警功能怎么开?
 干货   2023-08-06
女子4年卖2套房花700多万做美容:不但没变美脸,面部还出现变形
 百态   2023-08-04
住户一楼被水淹 还冲来8头猪
 百态   2023-07-31
女子体内爬出大量瓜子状活虫
 百态   2023-07-25
地球连续35年收到神秘规律性信号,网友:不要回答!
 探索   2023-07-21
全球镓价格本周大涨27%
 探索   2023-07-09
钱都流向了那些不缺钱的人,苦都留给了能吃苦的人
 探索   2023-07-02
倩女手游刀客魅者强控制(强混乱强眩晕强睡眠)和对应控制抗性的关系
 百态   2020-08-20
美国5月9日最新疫情:美国确诊人数突破131万
 百态   2020-05-09
荷兰政府宣布将集体辞职
 干货   2020-04-30
倩女幽魂手游师徒任务情义春秋猜成语答案逍遥观:鹏程万里
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案神机营:射石饮羽
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案昆仑山:拔刀相助
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案天工阁:鬼斧神工
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案丝路古道:单枪匹马
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:与虎谋皮
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:李代桃僵
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:指鹿为马
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案金陵:小鸟依人
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案金陵:千金买邻
 干货   2019-11-12
 
推荐阅读
 
 
 
>>返回首頁<<
 
靜靜地坐在廢墟上,四周的荒凉一望無際,忽然覺得,淒涼也很美
© 2005- 王朝網路 版權所有