【原创】代码与注解 22
　　恼人的注解
　　大家可能还记得中学语文课本的文言文吧。通常一篇几百字的文章会附带几页的名词解释和语法解释。文言文时代离我们是如此遥远，因此没有课文对当时的社会背景、语言习惯等做出注解，我们是没有办法明白这些晦涩的文字的意义的。然而，这些文字在其当时的文化氛围下，或者在当今的古文学专家面前是不需要注解的。程序注解的情况与此类似。



　　代码的一个主要作用是指挥计算机完成一个特定的功能，它的另一个作用是程序员间的思路交流。注解是交流的一种辅助手段——只是一种手段、而不是唯一手段。实现交流的手段还有：代码风格、设计文档和面对面的交谈等等。

　　不少编程教材都强调了注解的使用，其理由是程序代码不容易理解，的确对于大多数人理解别人的代码（有时候自己的代码也一样）比理解文言文难度更大。然而别忘了代码的主要作用，因此花在注解代码的时间应该远小于花在写代码的时间。


　　你有权保持沉默
　　代码不是文学作品，程序员不需要向文科学生揭示其算法，因此在写代码和注解的时候必须记住这些东西是给其他程序员看的，至少是给你的程序员同事看的，因此当你的中文系的女朋友要求你解释什么是KMP模式匹配算法的时候，你有权保持沉默。类似的，你不要：

　　1、注解代码中很清楚的事情，如果你通过仔细的命名规则书写你的代码你会发现注解是画蛇添足；例子：
　　　　a)　a=0;　　　　　　//a 是当前用户数，现将它初始化为0
　　　　b)　UserCount=0　　　//将当前用户数初始化为0
　　　　c)　dwUserCount=INIT_USER_COUNT

　　2、上一条的反过程就是：不要注解难懂的代码，相反试图思考代码的表达使代码本身更容易理解，而在注解中保持沉默。

　　3、不要注解标准算法，这些算法已经在其他文档中描述清楚，合格的程序员应该清楚，不过负责的程序员可以考虑在设计文档中指明该算法的出处，或者引用原文。（注意版权问题）

　　4、第3条推广，不要注解你自己的设计文档中已经描述清楚的事情。

　　5、不要注解给自己看，如果你确认你的代码只有你自己使用，而且你在今后的时间里能够记住这些代码的意义，可以集中精力书写代码而忽略注解。


　　明明白白我的心
　　作为开发队伍中的一员，你的代码必须交给别人使用或测试，这时候你必须从其他人的角度来思考问题。当你的代码是其他人的工具的时候，你必须保证这个工具是能用、好用而且容易掌握的。这时候你必须通过各种渠道竭力让你的同事、朋友或客户确实了解这些代码的使用方法、思路，代码注解将是一个有力的工具。好的代码加好的注解可以缩短你的技术支持时间、文档编写时间。有时一两行恰到好处的注解可以节省一整页文档的写作。

　　原则：
　　1、　公用函数、公用类的声明可以考虑用注解说明其使用方法和设计思路，当然选择恰当的命名和设计能够帮助你把事情解释得更清楚；
　　2、　全局变量、重要的常数一般必须注解；
　　3、　注意注解的排版整洁。一致的风格可以减少读者眼球的疲劳，同时节省你支持的时间。
　　4、　注解也需要维护，如果你修改了代码、注解必须同步修改。不要让注解变成过时的标语。

　　结束语
　　软件开发是一项充满创造性的工作，在其主要参与者——程序员的身上本不应该套满规范的枷锁。然而，这也是一个充满陷阱、失败和痛苦的世界。良好的规范并不在于禁止程序员做什么，而是只是程序员的工作指引。我不反对天才无视任何规范写出正确且高效的程序，甚至必要时我还会为使用他的代码而花时间去理解那些晦涩的语句。值得庆幸的是这种人不多。
    
关键词(Tags): 编程 注解
铁手 入典。铁手 荐,

Just keep it simple
代码写完就要添注释，编程不是一个人的事。

哈哈，注解写给自己看也是很重要的
经常发生几年后连这段程序是否是自己写的都糊涂的情况，还是看着开头的注解（我们都要留名字、时间，作为online documentation的一部分）才恍然大悟：原来是我这个WBD写的这破东西。注解对自己也很必要，否则没法弄清当时是怎么想的。

哈哈，古人比较适合写程序
我同意晨枫的看法，写注解给自己看也很重要。

当然，这也是有前提的，就是在一些改动是临时的，或者是权益之计，需要以后再做完善的情况下，写一些注解给自己看就很重要了。

话说回来，正常情况下，应该不常见才对。

曾经是这样
我也说了，是有前提的。
不过自从接受了敏捷开发的观点后，这部分的注解也基本没有了。
我现在的做法是，遇到觉得要注解的地方总是先考虑能否用更好的方式表达，也就是注解需求通常表示我的设计有问题。