关于在脚本中注释的几点建议和看法

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

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

　　为代码添加注释的最主要目的是提高代码可读性，但这里面更有一个心态问题：假如您认为，写了注释，就能够提高代码质量，就能够证实实力，那就错了，事情并没有那么简单。

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

　　……

　　'打开记录集，记录Orders表任何数据

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

　　……

　　objRS.Close '关闭记录集

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

　　……

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

　　写注释很大程度上也是为了防止自己以后读到这些代码的时候也不明其意，所以，假如能经常审视和改善以前代码中的注释……呵呵，还是不多说了吧，相信大家用膝盖想也能明白其中的好处。

标签：

版权申明：本站文章部分自网络，如有侵权，请联系：west999com@outlook.com
特别注意：本站所有转载文章言论不代表本站观点，本站所提供的摄影照片，插画，设计作品，如需使用，请与原作者联系，版权归原作者所有