<menu id="6923cc35"></menu>

        

  1. <source id="3c264ecd"></source>


  2. 
       
       
       


    狗万官网酒店 > 狗万官网下载 > 如何在JavaScript外方谨慎使用代码注释_javascript艺术

    如何在JavaScript外方谨慎使用代码注释_javascript艺术

    来源: 2019-08-04 19:43 我来投稿 参与评论
    这篇文章主要介绍了如何在JavaScript外方谨慎使用代码注释,必要的注解可以说明实现细节和规划意图,其一节约自己和他人的年月。 然而不少时候注释起的打算却适得其反,,要求的爱人可以参考下

    前言

    最令程序员头痛的事体莫过于阅读别人的编码,但其实时间一久阅读自己之编码也会很痛苦。 题目不是出在『友好或别人』,而是在代码本身。

    必要的注解可以说明实现细节和规划意图,其一节约自己和他人的年月。 然而不少时候注释起的打算却适得其反,比如自动生成的过多之注解分散阅读者之诱惑力, 而过期的失效的注解更是误导阅读者。

    机关生成的注解

    代码注释的泛滥想必是下Eclipse,Visual Studio等IDE初步的。 那些IDE提供了许多快捷功能,转变类/接口的骨架,具有Getter/Setter的习性等等。 如果用过IDE,下的编码你一贯不会陌生:

    /**
    * @param args
    */
    public static void main(String[] args) {
    // TODO Auto-generated method stub
    }

    上述6进代码中的4进注释包含的劳动量是0,既没有阐释参数args是何物,也没有说明main的用途。 然而大量之档次中都充斥着这样的自发性生成注释。

    『提议』:如果有数或机制需要说明,请补充这些信息。否则请删除自动生成注释。 当然,用于生成文档的注解除外。

    过多之注解

    大会有人不厌其烦地编写长篇累牍的注解,或无微不至,或语焉不详,或晦涩难懂,或文采飞扬。 总而言之没有帮助我更快阅读代码的注解都是失败的注解。

    为了说明问题,Harttle克隆了4.x Linux Kernel源码, 来大致分析一下其注释行数。 咱领略内核代码95%上述是C语言,故而统计.c文件就足够说明问题了。

    ➜ linux git:(master) git clone git@github.com:torvalds/linux.git --depth=1
    ➜ linux git:(master) find . -name "*.c" -o -name "*.h" -exec grep -E '^\s*((\*)|(/[/*]))' {} \; | wc -l
    724804
    ➜ linux git:(master) find . -name "*.c" -o -name "*.h" -exec cat {} \; | wc -l
    4018961
    ➜ linux git:(master) node
    > 724804/(4018961-724804)
    0.22002715717556875

    本仓库中的代码大概是402万行(未移除空行),其中注释72万行,占比22%。 Linux本使用低级的C语言编写,涉及到复杂的CPU布局、内存管理,驱动程序。 故而注释会偏多一些,一般说来的档次注释应小于这个数值。

    『提议』:如果你的编码中注释超过了20%,这就是说显然你过度注释了。

    文件头注释

    许多编辑器/IDE城市生成默认的公文头,例如:

    /**
    * @file /tmp/xxx.js
    * @author harttle(yangjvn@126.com)
    * @date 2016-08-30 22:33
    * @description A XXX Implementation for XXX.
    */

    文件头注释清晰地列出了文件的作者、效益描述等信息,瞧起来很有用。 不过这样的公文头存在的题目在于她维护性:

  3. 其他人做小的修改时未必会修改@author,甚至连@author都不掌握现在该文件已经面目全非。
  4. 每次移动该文件,是不是还要求花功夫更新 @file 消息?
  5. 孰会在每次代码修改后记得更新 @description,于是乎@description也总是误导读者
  6. 文件头注释意在保障代码文件的元信息,以便在分发和配置过程中保护作者版权等信息。 然而在获得版本控制的编码仓库中,那些信息不再需要手动维护,甚至可以通过git blame查阅每一行代码的作者和时间信息。

    『提议』:利用版本控制工具,删去文件头注释。自主经营权信息可在构建或分发时生成。

    冗余的注解

    图非常清楚的编码原则上不需要注释,剩下的注解反而会造成维护性问题。 尤其是非英语母语的作者常常会丢到这个坑里。比如变量和函数的注解:

    /*
    * 获取用户数量
    */
    function getUserCount(){
    // 我家之列表
    var userList = [];
    }

    这不是废话么!冗余的注解问题仍然在于维护性,例如调整函数功能、调整参数顺序, 或者转移变量名时我们不得不更新这些注释。否则这些注释就会误导下一个读者。

    【提议】:隐瞒废话。

    抽取注释到标识符

    可能读者也会有这样的阅历:顶我们写了一大段代码时,往往需要把它们分为几块。 接下来在每一块开头添加一段注释。例如:

    function calcTotalCharge(movies, user){
    // Calculate Movie Charge
    var movieCharge = 0;
    for(var i=0; i<movies.length; i++){
    var charge = 0;
    if(movie.type === 'discount'){
    charge = movie.charge * 0.8;
    }
    else if(movie.type === 'short'){
    charge = movie.charge * 2;
    }
    else if(movie.type === 'normal'){
    charge = movie.charge;
    }
    movieCharge += charge;
    }
    
    // Calculate User Charge
    var rentCharge = 0;
    if(user.isVIP1){
    rentCharge = 10;
    }
    if(user.isVIP2){
    rentCharge = 200;
    }
    else if(user.isVIP3){
    rentCharge = 300;
    }
    else if(user.isVIP4){
    rentCharge = 500;
    }
    // Calculate Total Charge
    return movieCharge + rentCharge;
    }

    上述代码中的三段注释确实加速了读书代码的进度, 但每当代码需要注释才能读懂时就应该警醒:是否结构设计有问题。 对于上述代码,咱可以通过更加可复用的组织来消除注释:

    function calcTotalCharge(movies, user){
    return calcMovieCharge(movies) + calcUserCharge(user);
    }
    function calcMovieCharge(movies){
    var total = 0;
    for(var i=0; i<movies.length; i++){
    total += calcSingleMovieCharge(movie);
    }
    return total;
    }
    function calcSingleMovieCharge(movie){
    if(movie.type === 'discount') return movie.charge * 0.8;
    else if(movie.type === 'short') return movie.charge * 2;
    else if(movie.type === 'normal') return movie.charge;
    return 0;
    }
    function calcUserCharge(user){
    if(user.isVIP1) return 10;
    else if(user.isVIP2) return 200;
    else if(user.isVIP3) return 300;
    else if(user.isVIP4) return 500;
    return 0;
    }

    代码重构之后原来的注解就变得毫无意义,代码意图都把清晰的发挥在标识符的命名中。 一般重构会带来代码量的减少,因为封装了分支、每个单元的逻辑也更加明朗。

    【提议】:顶我们发现不得不进行注释时,要求警醒是否结构设计发生了问题。

    使得之注解

    至今Harttle已描述了这么多反模式,并非为了说明代码注释不重要。 而是为了说明『代码注释存在的意思在于帮助理解代码本身』。 例如在编辑一些Trick,Polyfill,临时代码,以及复杂算法时,诠释变得相当重要。 例如:

  7. Tricks and Polyfills。有时简单的Trick就可解决多数问题问题, 为没必要编写复杂的普适算法, 例如检测浏览器的DOM API支持,检测AMD/CommonJS条件等等。 此刻我们需要清晰地表明这些Trick的图,甚至可以将这些代码抽离为polyfill模块。
  8. 复杂算法。有时我们会编写数学性非常强的打法,一眼望去不知所云。 在始发这些算法前清晰地表明他作用何在,读者也就不用花大功夫读懂这些数学了。
  9. 独资接口。模块的外面接口从逻辑上定义了模块类型,独资接口代码也更容易被人读到。 尤其是JavaScript接口:如果不注释options外方到底是什么,孰晓得接口如何使用。
  10. 上述就是本文的方方面面内容,瞩望对大家的上学有所帮助,也愿意大家多多支持脚本的师。

    义务编辑:狗万官网酒店
     
     
    0% (0)
     
     
    0% (0)
    机长评论( ) 请自觉遵守互联网相关的富民政策法规,不准发布色情、暴力、反动的议论。
    地名: 匿名?