西西河

主题:【原创】代码与注解 -- 代码ABC

共:💬5 🌺27
分页树展主题 · 全看首页 上页
/ 1
下页 末页
  • 家园 【原创】代码与注解

      恼人的注解

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

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

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

      你有权保持沉默

      代码不是文学作品,程序员不需要向文科学生揭示其算法,因此在写代码和注解的时候必须记住这些东西是给其他程序员看的,至少是给你的程序员同事看的,因此当你的中文系的女朋友要求你解释什么是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): #编程#注解元宝推荐:铁手,
    • 家园 曾经是这样

      我也说了,是有前提的。

      不过自从接受了敏捷开发的观点后,这部分的注解也基本没有了。

      我现在的做法是,遇到觉得要注解的地方总是先考虑能否用更好的方式表达,也就是注解需求通常表示我的设计有问题。

    • 家园 哈哈,古人比较适合写程序

      我同意晨枫的看法,写注解给自己看也很重要。

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

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

    • 家园 哈哈,注解写给自己看也是很重要的

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

    • 家园 Just keep it simple

      代码写完就要添注释,编程不是一个人的事。

分页树展主题 · 全看首页 上页
/ 1
下页 末页


有趣有益,互惠互利;开阔视野,博采众长。
虚拟的网络,真实的人。天南地北客,相逢皆朋友

Copyright © cchere 西西河