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

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

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

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

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

　　……
　　'打开记录集，记录Orders表所有数据
　　objRS.Open "SELECT * FROM Orders",objConn,1,1
　　……
　　objRS.Close '关闭记录集
　　Set objRS=Nothing '释放记录集对象
　　……

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

　　最后，祝所有专情的人好运！