正在阅读：关于脚本中注释的五点建议关于脚本中注释的五点建议

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

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

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

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

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

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

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

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

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

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

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

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

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