写程序的五个好习惯

虽然太阳很大，但是今天的温度却只有0~7度，昨天是阴天却不觉得有今天这么冷。我昨天心情挺好的，今天的心情却很郁闷，不是因为天气，而是因为 1500 行代码。

已经毕业的一位学长，给一个网站我改，本来应该是件好事，没想到很是令我郁闷。网站里面有一个弹出菜单，主菜单项只有六项，但是只菜单项比较多（就是链接比较多啦），需要在这个菜单上再添加 N 个项（N 也不小）。这个菜单是用 JavaScript 写的，本来我对 JavaScript 也不是特别熟悉，打开文件一看，立马傻眼，两段代码足有1500行（DW里可以看到的），没有任何缩进格式就不说了，而且变量名都是些毫无意义的字母和数字的组合，还特别长。最郁闷的是程序是有1500行，没有一行注释！所以郁闷的我要发几句牢骚：

1、程序要有格式，要适当的使用缩进。这样程序的层次结构才会看起来比较清晰，而且看你的程序的人也会感觉到一种美——赏心悦目。我看到有很多人，程序写了不少了，居然到现在写程序还是不会使用缩进，所有的代码都是左对齐的，没有一点层次感。缩进时一般使用 Tab 键，这个宽度会比较合适。程序是一种艺术，也要讲究美！

2、变量名要尽量有意义。不要图方便，随便用一些字母或数字做变量名，什么x,y,z,a,b,c,i,j之类的，但是你可以用几个英文单词组在一起做变量名，可以第一个字母小写，后面每个单词首字母大写，也可以几个单词之间用下画线连接，推荐使用前者。另外，变量名最好不要用汉字，原因是，不同的版本，不同的平台之间容易出现一些乱七八糟的错误。
[#afdream.com#]
3、最重要的一点：写程序一定要有注释！我想，只要你跟老师学过程序，你的老师一定强调要你在程序里面加上适当的注释！但是我至今仍不明白，为什么有人写程序就是不写注释？也许你今天知道你的程序是怎么写的，那么，若干天后呢？若干年后呢？你还能看懂么？而且我发现，在写程序注释的时候，对于自己检查程序错误有很大的帮助，和别人交流起来也非常方便，我们又何乐而不为呢？

4、还有，注意处理好各种运算符优先级。不要弄错了，记不得没有什么关系，加上括号就行了，这样在别人读的时候也不会引起歧义。

5、额外的：最好能够在程序的开头写名程序的名称、功能、时间、作者等信息。当你以后修改程序的时候会有很大的帮助。

PS：本来想找点相关的文章的，用百度居然没有搜到！自己在 CSDN 上到是发现一篇关于给程序写注释的文章，虽然文章中是拿脚本做例子，但是对于其他语言来说也应该是一样的：

标题：
关于脚本中注释的五点建议
原文地址：
http://blog.csdn.net/estyle/archive/2004/07/05/34722.aspx
作者：靳田
作者Blog：http://blog.csdn.net/Estyle/

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

　　一、切勿为了注释而注释！
　　为代码添加注释的最主要目的是提高代码可读性，但这里面还有一个心态问题：如果你认为，写了注释，就可以提高代码质量，就可以证明实力，那就错了，事情并没有那么简单。
　　相信一定有人在写注释的时候，没有把握正确的心态，这就导致写出来的注释往往不合时宜。什么是不合时宜的注释？我就写过这样的注释：
　　……
　　’打开记录集，记录Orders表所有数据
　　objRS.Open “SELECT * FROM Orders”,objConn,1,1
　　……
　　objRS.Close ‘关闭记录集
　　Set objRS=Nothing ‘释放记录集对象
　　……
　　明白了吧？这就是不合时宜的注释的情形之一：形式化的注释，往往会成为代码的累赘，甚至无法突出真正需要注释的地方，降低了代码的可读性。
　　这都是心态没有把握好的原因。如果能正确把握心态，就会把心思放到提高代码可读性上，而不是放到写注释上了！写注释只是提高代码可读性的手段之一，而且写注释也是要讲技巧和效率的。下面将对此进行讨论。

　　二、废话连篇的注释不是好注释！
　　在我看来，优秀的命名规范和代码格式往往比注释更能提高代码可读性。命名规范可以说明代码元素的作用，而代码格式则能使编程思路更清晰——不过很遗憾，它们无论如何都跳不出代码的圈圈，对代码的描述能力并不强，所以我们还是要依靠注释。
　　因此，我们应该先在命名规范和代码格式两个方面严格要求自己，然后再以注释为辅助来描述代码。——请不要怀疑，你读代码的时候是先看代码还是先看注释？一般的情况是，代码能明确说明的问题往往就不需要看注释了，比如上面第一点里写出的那些垃圾注释，没人会把它们当回事的（但被当作入门教程中的示例还不错）。当然，也有例外，以注释为代码主要描述手段的情况在第三点讨论。
　　什么样的注释才是合时宜的呢？在适当的地方，以适当的篇幅写出来的注释就是合时宜的。我不能给你更具体的答案，但方向已经指明了，你需要做的就是思考、参考、再思考……总之，让注释也和代码一样简单、优雅而又有效就是目标，这样的代码才能达到提高代码可读性的效果！
　　仅仅是合时宜还不够，如果注释含糊不清，仍然不是好注释！所以，让注释更准确地描述代码同样重要，特别是对函数/过程、技巧性质的代码段等。以昨天那篇文章（你抄近道了吗？——源自两个VBS过程的感慨）中提到的两个过程之一——GetRandom——为例，我为其作用的描述是：返回从源数组中随机抽取指定数目的位置不重复元素组成的新数组。如果让你描述它的作用，你会如何描述？请不要误会，我可不是在自卖自夸，我只是取了一个离自己最近的例子而已。
　　总之，好的注释，要合时宜，还要准确有效！否则不如不写。

　　三、外部文档往往比内部注释更有效！
　　你也许会奇怪，我上面强调了函数/过程和技巧性质的代码段的注释要准确，为什么我没有提到对类的注释呢？个人以为，如果程序广泛采用了面向（或者基于）对象的设计方法，对类的注释应该从长计议。情况之一是，如果类需要封装，那注释也只在设计时有效，对提高代码可读性的意义不大；情况之二是，类的设计和使用应该宏观把握，而代码中的注释往往是微观的描述，很难达到宏观描述的效果——比如许多用图才好描述的类关系，注释的效果就不好。
　　这个时候，我们就需要有外部文档了！不要问我什么是外部文档，如何写外部文档。总之，一切为提高代码可读性服务，做你能做的一切。
　　还有一个问题要说，到底该在什么时候写注释和文档呢？有些人是先把代码写好，再趁着自己没有淡忘之前把注释补上；有些人先写好设计草案，然后再开始写代码……其实没有对错，达到目的就好。——注意，理性统筹的正规项目工程开发不在讨论范围内，这种开发要考虑的因素太多了，不能那么随意的。

　　四、尽量避免客户端注释！
　　客户端注释的唯一缺点应该是增加I/O压力吧？大家可以算一算，如果为HTML和客户端脚本添加注释，主观估计将为每页增加1K字节，现在剩下的就是估计页访问量了……
　　为什么要为客户端脚本和HTML添加注释呢？特别是为HTML添加注释更是难以理解——也可能是我没见识吧，呵呵。标准化的B/S客户端设计讲究结构、呈现、行为的分离，我想这是对客户端代码最好的注释吧？

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