• underscore-1.8.3-analysis.js


       1 //     Underscore.js 1.8.3
       2 //     http://underscorejs.org
       3 //     (c) 2009-2015 Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors
       4 //     Underscore may be freely distributed under the MIT license.
       5 //     中文注释 by hanzichi @https://github.com/hanzichi
       6 //     我的源码解读顺序(跟系列解读文章相对应)
       7 //     Object -> Array -> Collection -> Function -> Utility
       8 
       9 (function() {
      10 
      11   // Baseline setup
      12   // 基本设置、配置
      13   // --------------
      14 
      15   // Establish the root object, `window` in the browser, or `exports` on the server.
      16   // 将 this 赋值给局部变量 root
      17   // root 的值, 客户端为 `window`, 服务端(node) 中为 `exports`
      18   var root = this;
      19 
      20   // Save the previous value of the `_` variable.
      21   // 将原来全局环境中的变量 `_` 赋值给变量 previousUnderscore 进行缓存
      22   // 在后面的 noConflict 方法中有用到
      23   var previousUnderscore = root._;
      24 
      25   // Save bytes in the minified (but not gzipped) version:
      26   // 缓存变量, 便于压缩代码
      27   // 此处「压缩」指的是压缩到 min.js 版本
      28   // 而不是 gzip 压缩
      29   var ArrayProto = Array.prototype, ObjProto = Object.prototype, FuncProto = Function.prototype;
      30 
      31   // Create quick reference variables for speed access to core prototypes.
      32   // 缓存变量, 便于压缩代码
      33   // 同时可减少在原型链中的查找次数(提高代码效率)
      34   var
      35     push             = ArrayProto.push,
      36     slice            = ArrayProto.slice,
      37     toString         = ObjProto.toString,
      38     hasOwnProperty   = ObjProto.hasOwnProperty;
      39 
      40   // All **ECMAScript 5** native function implementations that we hope to use
      41   // are declared here.
      42   // ES5 原生方法, 如果浏览器支持, 则 underscore 中会优先使用
      43   var
      44     nativeIsArray      = Array.isArray,
      45     nativeKeys         = Object.keys,
      46     nativeBind         = FuncProto.bind,
      47     nativeCreate       = Object.create;
      48 
      49   // Naked function reference for surrogate-prototype-swapping.
      50   var Ctor = function(){};
      51 
      52   // Create a safe reference to the Underscore object for use below.
      53   // 核心函数
      54   // `_` 其实是一个构造函数
      55   // 支持无 new 调用的构造函数(思考 jQuery 的无 new 调用)
      56   // 将传入的参数(实际要操作的数据)赋值给 this._wrapped 属性
      57   // OOP 调用时,_ 相当于一个构造函数
      58   // each 等方法都在该构造函数的原型链上
      59   // _([1, 2, 3]).each(alert)
      60   // _([1, 2, 3]) 相当于无 new 构造了一个新的对象
      61   // 调用了该对象的 each 方法,该方法在该对象构造函数的原型链上
      62   var _ = function(obj) {
      63     // 以下均针对 OOP 形式的调用
      64     // 如果是非 OOP 形式的调用,不会进入该函数内部
      65 
      66     // 如果 obj 已经是 `_` 函数的实例,则直接返回 obj
      67     if (obj instanceof _)
      68       return obj;
      69 
      70     // 如果不是 `_` 函数的实例
      71     // 则调用 new 运算符,返回实例化的对象
      72     if (!(this instanceof _))
      73       return new _(obj);
      74 
      75     // 将 obj 赋值给 this._wrapped 属性
      76     this._wrapped = obj;
      77   };
      78 
      79   // Export the Underscore object for **Node.js**, with
      80   // backwards-compatibility for the old `require()` API. If we're in
      81   // the browser, add `_` as a global object.
      82   // 将上面定义的 `_` 局部变量赋值给全局对象中的 `_` 属性
      83   // 即客户端中 window._ = _
      84   // 服务端(node)中 exports._ = _
      85   // 同时在服务端向后兼容老的 require() API
      86   // 这样暴露给全局后便可以在全局环境中使用 `_` 变量(方法)
      87   if (typeof exports !== 'undefined') {
      88     if (typeof module !== 'undefined' && module.exports) {
      89       exports = module.exports = _;
      90     }
      91     exports._ = _;
      92   } else {
      93     root._ = _;
      94   }
      95 
      96   // Current version.
      97   // 当前 underscore 版本号
      98   _.VERSION = '1.8.3';
      99 
     100   // Internal function that returns an efficient (for current engines) version
     101   // of the passed-in callback, to be repeatedly applied in other Underscore
     102   // functions.
     103   // underscore 内部方法
     104   // 根据 this 指向(context 参数)
     105   // 以及 argCount 参数
     106   // 二次操作返回一些回调、迭代方法
     107   var optimizeCb = function(func, context, argCount) {
     108     // 如果没有指定 this 指向,则返回原函数
     109     if (context === void 0) return func;
     110 
     111     switch (argCount == null ? 3 : argCount) {
     112       case 1: return function(value) {
     113         return func.call(context, value);
     114       };
     115       case 2: return function(value, other) {
     116         return func.call(context, value, other);
     117       };
     118 
     119       // 如果有指定 this,但没有传入 argCount 参数
     120       // 则执行以下 case
     121       // _.each、_.map
     122       case 3: return function(value, index, collection) {
     123         return func.call(context, value, index, collection);
     124       };
     125 
     126       // _.reduce、_.reduceRight
     127       case 4: return function(accumulator, value, index, collection) {
     128         return func.call(context, accumulator, value, index, collection);
     129       };
     130     }
     131     return function() {
     132       return func.apply(context, arguments);
     133     };
     134   };
     135 
     136   // A mostly-internal function to generate callbacks that can be applied
     137   // to each element in a collection, returning the desired result — either
     138   // identity, an arbitrary callback, a property matcher, or a property accessor.
     139   var cb = function(value, context, argCount) {
     140     if (value == null) return _.identity;
     141     if (_.isFunction(value)) return optimizeCb(value, context, argCount);
     142     if (_.isObject(value)) return _.matcher(value);
     143     return _.property(value);
     144   };
     145 
     146   _.iteratee = function(value, context) {
     147     return cb(value, context, Infinity);
     148   };
     149 
     150   // An internal function for creating assigner functions.
     151   // 有三个方法用到了这个内部函数
     152   // _.extend & _.extendOwn & _.defaults
     153   // _.extend = createAssigner(_.allKeys);
     154   // _.extendOwn = _.assign = createAssigner(_.keys);
     155   // _.defaults = createAssigner(_.allKeys, true);
     156   var createAssigner = function(keysFunc, undefinedOnly) {
     157     // 返回函数
     158     // 经典闭包(undefinedOnly 参数在返回的函数中被引用)
     159     // 返回的函数参数个数 >= 1
     160     // 将第二个开始的对象参数的键值对 "继承" 给第一个参数
     161     return function(obj) {
     162       var length = arguments.length;
     163       // 只传入了一个参数(或者 0 个?)
     164       // 或者传入的第一个参数是 null
     165       if (length < 2 || obj == null) return obj;
     166 
     167       // 枚举第一个参数除外的对象参数
     168       // 即 arguments[1], arguments[2] ...
     169       for (var index = 1; index < length; index++) {
     170         // source 即为对象参数
     171         var source = arguments[index],
     172             // 提取对象参数的 keys 值
     173             // keysFunc 参数表示 _.keys
     174             // 或者 _.allKeys
     175             keys = keysFunc(source),
     176             l = keys.length;
     177 
     178         // 遍历该对象的键值对
     179         for (var i = 0; i < l; i++) {
     180           var key = keys[i];
     181           // _.extend 和 _.extendOwn 方法
     182           // 没有传入 undefinedOnly 参数,即 !undefinedOnly 为 true
     183           // 即肯定会执行 obj[key] = source[key]
     184           // 后面对象的键值对直接覆盖 obj
     185           // ==========================================
     186           // _.defaults 方法,undefinedOnly 参数为 true
     187           // 即 !undefinedOnly 为 false
     188           // 那么当且仅当 obj[key] 为 undefined 时才覆盖
     189           // 即如果有相同的 key 值,取最早出现的 value 值
     190           // *defaults 中有相同 key 的也是一样取首次出现的
     191           if (!undefinedOnly || obj[key] === void 0)
     192             obj[key] = source[key];
     193         }
     194       }
     195 
     196       // 返回已经继承后面对象参数属性的第一个参数对象
     197       return obj;
     198     };
     199   };
     200 
     201   // An internal function for creating a new object that inherits from another.
     202   // use in `_.create`
     203   var baseCreate = function(prototype) {
     204     // 如果 prototype 参数不是对象
     205     if (!_.isObject(prototype)) return {};
     206 
     207     // 如果浏览器支持 ES5 Object.create
     208     if (nativeCreate) return nativeCreate(prototype);
     209 
     210     Ctor.prototype = prototype;
     211     var result = new Ctor;
     212     Ctor.prototype = null;
     213     return result;
     214   };
     215 
     216   // 闭包
     217   var property = function(key) {
     218     return function(obj) {
     219       return obj == null ? void 0 : obj[key];
     220     };
     221   };
     222 
     223   // Helper for collection methods to determine whether a collection
     224   // should be iterated as an array or as an object
     225   // Related: http://people.mozilla.org/~jorendorff/es6-draft.html#sec-tolength
     226   // Avoids a very nasty iOS 8 JIT bug on ARM-64. #2094
     227 
     228   // Math.pow(2, 53) - 1 是 JavaScript 中能精确表示的最大数字
     229   var MAX_ARRAY_INDEX = Math.pow(2, 53) - 1;
     230 
     231   // getLength 函数
     232   // 该函数传入一个参数,返回参数的 length 属性值
     233   // 用来获取 array 以及 arrayLike 元素的 length 属性值
     234   var getLength = property('length');
     235 
     236   // 判断是否是 ArrayLike Object
     237   // 类数组,即拥有 length 属性并且 length 属性值为 Number 类型的元素
     238   // 包括数组、arguments、HTML Collection 以及 NodeList 等等
     239   // 包括类似 {length: 10} 这样的对象
     240   // 包括字符串、函数等
     241   var isArrayLike = function(collection) {
     242     // 返回参数 collection 的 length 属性值
     243     var length = getLength(collection);
     244     return typeof length == 'number' && length >= 0 && length <= MAX_ARRAY_INDEX;
     245   };
     246 
     247 
     248   // Collection Functions
     249   // 数组或者对象的扩展方法
     250   // 共 25 个扩展方法
     251   // --------------------
     252 
     253   // The cornerstone, an `each` implementation, aka `forEach`.
     254   // Handles raw objects in addition to array-likes. Treats all
     255   // sparse array-likes as if they were dense.
     256   // 与 ES5 中 Array.prototype.forEach 使用方法类似
     257   // 遍历数组或者对象的每个元素
     258   // 第一个参数为数组(包括类数组)或者对象
     259   // 第二个参数为迭代方法,对数组或者对象每个元素都执行该方法
     260   // 该方法又能传入三个参数,分别为 (item, index, array)((value, key, obj) for object)
     261   // 与 ES5 中 Array.prototype.forEach 方法传参格式一致
     262   // 第三个参数(可省略)确定第二个参数 iteratee 函数中的(可能有的)this 指向
     263   // 即 iteratee 中出现的(如果有)所有 this 都指向 context
     264   // notice: 不要传入一个带有 key 类型为 number 的对象!
     265   // notice: _.each 方法不能用 return 跳出循环(同样,Array.prototype.forEach 也不行)
     266   _.each = _.forEach = function(obj, iteratee, context) {
     267     // 根据 context 确定不同的迭代函数
     268     iteratee = optimizeCb(iteratee, context);
     269 
     270     var i, length;
     271 
     272     // 如果是类数组
     273     // 默认不会传入类似 {length: 10} 这样的数据
     274     if (isArrayLike(obj)) {
     275       // 遍历
     276       for (i = 0, length = obj.length; i < length; i++) {
     277         iteratee(obj[i], i, obj);
     278       }
     279     } else { // 如果 obj 是对象
     280       // 获取对象的所有 key 值
     281       var keys = _.keys(obj);
     282 
     283       // 如果是对象,则遍历处理 values 值
     284       for (i = 0, length = keys.length; i < length; i++) {
     285         iteratee(obj[keys[i]], keys[i], obj); // (value, key, obj)
     286       }
     287     }
     288 
     289     // 返回 obj 参数
     290     // 供链式调用(Returns the list for chaining)
     291     // 应该仅 OOP 调用有效
     292     return obj;
     293   };
     294 
     295   // Return the results of applying the iteratee to each element.
     296   // 与 ES5 中 Array.prototype.map 使用方法类似
     297   // 传参形式与 _.each 方法类似
     298   // 遍历数组(每个元素)或者对象的每个元素(value)
     299   // 对每个元素执行 iteratee 迭代方法
     300   // 将结果保存到新的数组中,并返回
     301   _.map = _.collect = function(obj, iteratee, context) {
     302     // 根据 context 确定不同的迭代函数
     303     iteratee = cb(iteratee, context);
     304 
     305     // 如果传参是对象,则获取它的 keys 值数组(短路表达式)
     306     var keys = !isArrayLike(obj) && _.keys(obj),
     307         // 如果 obj 为对象,则 length 为 key.length
     308         // 如果 obj 为数组,则 length 为 obj.length
     309         length = (keys || obj).length,
     310         results = Array(length); // 结果数组
     311 
     312     // 遍历
     313     for (var index = 0; index < length; index++) {
     314       // 如果 obj 为对象,则 currentKey 为对象键值 key
     315       // 如果 obj 为数组,则 currentKey 为 index 值
     316       var currentKey = keys ? keys[index] : index;
     317       results[index] = iteratee(obj[currentKey], currentKey, obj);
     318     }
     319 
     320     // 返回新的结果数组
     321     return results;
     322   };
     323 
     324   // Create a reducing function iterating left or right.
     325   // dir === 1 -> _.reduce
     326   // dir === -1 -> _.reduceRight
     327   function createReduce(dir) {
     328     // Optimized iterator function as using arguments.length
     329     // in the main function will deoptimize the, see #1991.
     330     function iterator(obj, iteratee, memo, keys, index, length) {
     331       for (; index >= 0 && index < length; index += dir) {
     332         var currentKey = keys ? keys[index] : index;
     333         // 迭代,返回值供下次迭代调用
     334         memo = iteratee(memo, obj[currentKey], currentKey, obj);
     335       }
     336       // 每次迭代返回值,供下次迭代调用
     337       return memo;
     338     }
     339 
     340     // _.reduce(_.reduceRight)可传入的 4 个参数
     341     // obj 数组或者对象
     342     // iteratee 迭代方法,对数组或者对象每个元素执行该方法
     343     // memo 初始值,如果有,则从 obj 第一个元素开始迭代
     344     // 如果没有,则从 obj 第二个元素开始迭代,将第一个元素作为初始值
     345     // context 为迭代函数中的 this 指向
     346     return function(obj, iteratee, memo, context) {
     347       iteratee = optimizeCb(iteratee, context, 4);
     348       var keys = !isArrayLike(obj) && _.keys(obj),
     349           length = (keys || obj).length,
     350           index = dir > 0 ? 0 : length - 1;
     351 
     352       // Determine the initial value if none is provided.
     353       // 如果没有指定初始值
     354       // 则把第一个元素指定为初始值
     355       if (arguments.length < 3) {
     356         memo = obj[keys ? keys[index] : index];
     357         // 根据 dir 确定是向左还是向右遍历
     358         index += dir;
     359       }
     360 
     361       return iterator(obj, iteratee, memo, keys, index, length);
     362     };
     363   }
     364 
     365   // **Reduce** builds up a single result from a list of values, aka `inject`,
     366   // or `foldl`.
     367   // 与 ES5 中 Array.prototype.reduce 使用方法类似
     368   // _.reduce(list, iteratee, [memo], [context])
     369   // _.reduce 方法最多可传入 4 个参数
     370   // memo 为初始值,可选
     371   // context 为指定 iteratee 中 this 指向,可选
     372   _.reduce = _.foldl = _.inject = createReduce(1);
     373 
     374   // The right-associative version of reduce, also known as `foldr`.
     375   // 与 ES5 中 Array.prototype.reduceRight 使用方法类似
     376   _.reduceRight = _.foldr = createReduce(-1);
     377 
     378   // Return the first value which passes a truth test. Aliased as `detect`.
     379   // 寻找数组或者对象中第一个满足条件(predicate 函数返回 true)的元素
     380   // 并返回该元素值
     381   // _.find(list, predicate, [context])
     382   _.find = _.detect = function(obj, predicate, context) {
     383     var key;
     384     // 如果 obj 是数组,key 为满足条件的下标
     385     if (isArrayLike(obj)) {
     386       key = _.findIndex(obj, predicate, context);
     387     } else {
     388       // 如果 obj 是对象,key 为满足条件的元素的 key 值
     389       key = _.findKey(obj, predicate, context);
     390     }
     391 
     392     // 如果该元素存在,则返回该元素
     393     // 如果不存在,则默认返回 undefined(函数没有返回,即返回 undefined)
     394     if (key !== void 0 && key !== -1) return obj[key];
     395   };
     396 
     397   // Return all the elements that pass a truth test.
     398   // Aliased as `select`.
     399   // 与 ES5 中 Array.prototype.filter 使用方法类似
     400   // 寻找数组或者对象中所有满足条件的元素
     401   // 如果是数组,则将 `元素值` 存入数组
     402   // 如果是对象,则将 `value 值` 存入数组
     403   // 返回该数组
     404   // _.filter(list, predicate, [context])
     405   _.filter = _.select = function(obj, predicate, context) {
     406     var results = [];
     407 
     408     // 根据 this 指向,返回 predicate 函数(判断函数)
     409     predicate = cb(predicate, context);
     410 
     411     // 遍历每个元素,如果符合条件则存入数组
     412     _.each(obj, function(value, index, list) {
     413       if (predicate(value, index, list)) results.push(value);
     414     });
     415 
     416     return results;
     417   };
     418 
     419   // Return all the elements for which a truth test fails.
     420   // 寻找数组或者对象中所有不满足条件的元素
     421   // 并以数组方式返回
     422   // 所得结果是 _.filter 方法的补集
     423   _.reject = function(obj, predicate, context) {
     424     return _.filter(obj, _.negate(cb(predicate)), context);
     425   };
     426 
     427   // Determine whether all of the elements match a truth test.
     428   // Aliased as `all`.
     429   // 与 ES5 中的 Array.prototype.every 方法类似
     430   // 判断数组中的每个元素或者对象中每个 value 值是否都满足 predicate 函数中的判断条件
     431   // 如果是,则返回 ture;否则返回 false(有一个不满足就返回 false)
     432   // _.every(list, [predicate], [context])
     433   _.every = _.all = function(obj, predicate, context) {
     434     // 根据 this 指向,返回相应 predicate 函数
     435     predicate = cb(predicate, context);
     436 
     437     var keys = !isArrayLike(obj) && _.keys(obj),
     438         length = (keys || obj).length;
     439 
     440     for (var index = 0; index < length; index++) {
     441       var currentKey = keys ? keys[index] : index;
     442       // 如果有一个不能满足 predicate 中的条件
     443       // 则返回 false
     444       if (!predicate(obj[currentKey], currentKey, obj))
     445         return false;
     446     }
     447 
     448     return true;
     449   };
     450 
     451   // Determine if at least one element in the object matches a truth test.
     452   // Aliased as `any`.
     453   // 与 ES5 中 Array.prototype.some 方法类似
     454   // 判断数组或者对象中是否有一个元素(value 值 for object)满足 predicate 函数中的条件
     455   // 如果是则返回 true;否则返回 false
     456   // _.some(list, [predicate], [context])
     457   _.some = _.any = function(obj, predicate, context) {
     458     // 根据 context 返回 predicate 函数
     459     predicate = cb(predicate, context);
     460     // 如果传参是对象,则返回该对象的 keys 数组
     461     var keys = !isArrayLike(obj) && _.keys(obj),
     462         length = (keys || obj).length;
     463     for (var index = 0; index < length; index++) {
     464       var currentKey = keys ? keys[index] : index;
     465       // 如果有一个元素满足条件,则返回 true
     466       if (predicate(obj[currentKey], currentKey, obj)) return true;
     467     }
     468     return false;
     469   };
     470 
     471   // Determine if the array or object contains a given item (using `===`).
     472   // Aliased as `includes` and `include`.
     473   // 判断数组或者对象中(value 值)是否有指定元素
     474   // 如果是 object,则忽略 key 值,只需要查找 value 值即可
     475   // 即该 obj 中是否有指定的 value 值
     476   // 返回布尔值
     477   _.contains = _.includes = _.include = function(obj, item, fromIndex, guard) {
     478     // 如果是对象,返回 values 组成的数组
     479     if (!isArrayLike(obj)) obj = _.values(obj);
     480 
     481     // fromIndex 表示查询起始位置
     482     // 如果没有指定该参数,则默认从头找起
     483     if (typeof fromIndex != 'number' || guard) fromIndex = 0;
     484 
     485     // _.indexOf 是数组的扩展方法(Array Functions)
     486     // 数组中寻找某一元素
     487     return _.indexOf(obj, item, fromIndex) >= 0;
     488   };
     489 
     490   // Invoke a method (with arguments) on every item in a collection.
     491   // Calls the method named by methodName on each value in the list.
     492   // Any extra arguments passed to invoke will be forwarded on to the method invocation.
     493   // 数组或者对象中的每个元素都调用 method 方法
     494   // 返回调用后的结果(数组或者关联数组)
     495   // method 参数后的参数会被当做参数传入 method 方法中
     496   // _.invoke(list, methodName, *arguments)
     497   _.invoke = function(obj, method) {
     498     // *arguments 参数
     499     var args = slice.call(arguments, 2);
     500 
     501     // 判断 method 是不是函数
     502     var isFunc = _.isFunction(method);
     503 
     504     // 用 map 方法对数组或者对象每个元素调用方法
     505     // 返回数组
     506     return _.map(obj, function(value) {
     507       // 如果 method 不是函数,则可能是 obj 的 key 值
     508       // 而 obj[method] 可能为函数
     509       var func = isFunc ? method : value[method];
     510       return func == null ? func : func.apply(value, args);
     511     });
     512   };
     513 
     514   // Convenience version of a common use case of `map`: fetching a property.
     515   // 一个数组,元素都是对象
     516   // 根据指定的 key 值
     517   // 返回一个数组,元素都是指定 key 值的 value 值
     518   /*
     519   var property = function(key) {
     520     return function(obj) {
     521       return obj == null ? void 0 : obj[key];
     522     };
     523   };
     524   */
     525   // _.pluck(list, propertyName)
     526   _.pluck = function(obj, key) {
     527     return _.map(obj, _.property(key));
     528   };
     529 
     530   // Convenience version of a common use case of `filter`: selecting only objects
     531   // containing specific `key:value` pairs.
     532   // 根据指定的键值对
     533   // 选择对象
     534   _.where = function(obj, attrs) {
     535     return _.filter(obj, _.matcher(attrs));
     536   };
     537 
     538   // Convenience version of a common use case of `find`: getting the first object
     539   // containing specific `key:value` pairs.
     540   // 寻找第一个有指定 key-value 键值对的对象
     541   _.findWhere = function(obj, attrs) {
     542     return _.find(obj, _.matcher(attrs));
     543   };
     544 
     545   // Return the maximum element (or element-based computation).
     546   // 寻找数组中的最大元素
     547   // 或者对象中的最大 value 值
     548   // 如果有 iteratee 参数,则求每个元素经过该函数迭代后的最值
     549   // _.max(list, [iteratee], [context])
     550   _.max = function(obj, iteratee, context) {
     551     var result = -Infinity, lastComputed = -Infinity,
     552         value, computed;
     553 
     554     // 单纯地寻找最值
     555     if (iteratee == null && obj != null) {
     556       // 如果是数组,则寻找数组中最大元素
     557       // 如果是对象,则寻找最大 value 值
     558       obj = isArrayLike(obj) ? obj : _.values(obj);
     559 
     560       for (var i = 0, length = obj.length; i < length; i++) {
     561         value = obj[i];
     562         if (value > result) {
     563           result = value;
     564         }
     565       }
     566     } else {  // 寻找元素经过迭代后的最值
     567       iteratee = cb(iteratee, context);
     568 
     569       // result 保存结果元素
     570       // lastComputed 保存计算过程中出现的最值
     571       // 遍历元素
     572       _.each(obj, function(value, index, list) {
     573         // 经过迭代函数后的值
     574         computed = iteratee(value, index, list);
     575         // && 的优先级高于 ||
     576         if (computed > lastComputed || computed === -Infinity && result === -Infinity) {
     577           result = value;
     578           lastComputed = computed;
     579         }
     580       });
     581     }
     582 
     583     return result;
     584   };
     585 
     586   // Return the minimum element (or element-based computation).
     587   // 寻找最小的元素
     588   // 类似 _.max
     589   // _.min(list, [iteratee], [context])
     590   _.min = function(obj, iteratee, context) {
     591     var result = Infinity, lastComputed = Infinity,
     592         value, computed;
     593     if (iteratee == null && obj != null) {
     594       obj = isArrayLike(obj) ? obj : _.values(obj);
     595       for (var i = 0, length = obj.length; i < length; i++) {
     596         value = obj[i];
     597         if (value < result) {
     598           result = value;
     599         }
     600       }
     601     } else {
     602       iteratee = cb(iteratee, context);
     603       _.each(obj, function(value, index, list) {
     604         computed = iteratee(value, index, list);
     605         if (computed < lastComputed || computed === Infinity && result === Infinity) {
     606           result = value;
     607           lastComputed = computed;
     608         }
     609       });
     610     }
     611     return result;
     612   };
     613 
     614   // Shuffle a collection, using the modern version of the
     615   // [Fisher-Yates shuffle](http://en.wikipedia.org/wiki/Fisher–Yates_shuffle).
     616   // 将数组乱序
     617   // 如果是对象,则返回一个数组,数组由对象 value 值构成
     618   // Fisher-Yates shuffle 算法
     619   // 最优的洗牌算法,复杂度 O(n)
     620   // 乱序不要用 sort + Math.random(),复杂度 O(nlogn)
     621   // 而且,并不是真正的乱序
     622   // @see https://github.com/hanzichi/underscore-analysis/issues/15
     623   _.shuffle = function(obj) {
     624     // 如果是对象,则对 value 值进行乱序
     625     var set = isArrayLike(obj) ? obj : _.values(obj);
     626     var length = set.length;
     627 
     628     // 乱序后返回的数组副本(参数是对象则返回乱序后的 value 数组)
     629     var shuffled = Array(length);
     630 
     631     // 枚举元素
     632     for (var index = 0, rand; index < length; index++) {
     633       // 将当前所枚举位置的元素和 `index=rand` 位置的元素交换
     634       rand = _.random(0, index);
     635       if (rand !== index) shuffled[index] = shuffled[rand];
     636       shuffled[rand] = set[index];
     637     }
     638 
     639     return shuffled;
     640   };
     641 
     642   // Sample **n** random values from a collection.
     643   // If **n** is not specified, returns a single random element.
     644   // The internal `guard` argument allows it to work with `map`.
     645   // 随机返回数组或者对象中的一个元素
     646   // 如果指定了参数 `n`,则随机返回 n 个元素组成的数组
     647   // 如果参数是对象,则数组由 values 组成
     648   _.sample = function(obj, n, guard) {
     649     // 随机返回一个元素
     650     if (n == null || guard) {
     651       if (!isArrayLike(obj)) obj = _.values(obj);
     652       return obj[_.random(obj.length - 1)];
     653     }
     654 
     655     // 随机返回 n 个
     656     return _.shuffle(obj).slice(0, Math.max(0, n));
     657   };
     658 
     659   // Sort the object's values by a criterion produced by an iteratee.
     660   // 排序
     661   // _.sortBy(list, iteratee, [context])
     662   _.sortBy = function(obj, iteratee, context) {
     663     iteratee = cb(iteratee, context);
     664 
     665     // 根据指定的 key 返回 values 数组
     666     // _.pluck([{}, {}, {}], 'value')
     667     return _.pluck(
     668       // _.map(obj, function(){}).sort()
     669       // _.map 后的结果 [{}, {}..]
     670       // sort 后的结果 [{}, {}..]
     671       _.map(obj, function(value, index, list) {
     672         return {
     673           value: value,
     674           index: index,
     675           // 元素经过迭代函数迭代后的值
     676           criteria: iteratee(value, index, list)
     677         };
     678       }).sort(function(left, right) {
     679       var a = left.criteria;
     680       var b = right.criteria;
     681       if (a !== b) {
     682         if (a > b || a === void 0) return 1;
     683         if (a < b || b === void 0) return -1;
     684       }
     685       return left.index - right.index;
     686     }), 'value');
     687 
     688   };
     689 
     690   // An internal function used for aggregate "group by" operations.
     691   // behavior 是一个函数参数
     692   // _.groupBy, _.indexBy 以及 _.countBy 其实都是对数组元素进行分类
     693   // 分类规则就是 behavior 函数
     694   var group = function(behavior) {
     695     return function(obj, iteratee, context) {
     696       // 返回结果是一个对象
     697       var result = {};
     698       iteratee = cb(iteratee, context);
     699       // 遍历元素
     700       _.each(obj, function(value, index) {
     701         // 经过迭代,获取结果值,存为 key
     702         var key = iteratee(value, index, obj);
     703         // 按照不同的规则进行分组操作
     704         // 将变量 result 当做参数传入,能在 behavior 中改变该值
     705         behavior(result, value, key);
     706       });
     707       // 返回结果对象
     708       return result;
     709     };
     710   };
     711 
     712   // Groups the object's values by a criterion. Pass either a string attribute
     713   // to group by, or a function that returns the criterion.
     714   // groupBy_  _.groupBy(list, iteratee, [context])
     715   // 根据特定规则对数组或者对象中的元素进行分组
     716   // result 是返回对象
     717   // value 是数组元素
     718   // key 是迭代后的值
     719   _.groupBy = group(function(result, value, key) {
     720     // 根据 key 值分组
     721     // key 是元素经过迭代函数后的值
     722     // 或者元素自身的属性值
     723 
     724     // result 对象已经有该 key 值了
     725     if (_.has(result, key))
     726       result[key].push(value);
     727     else result[key] = [value];
     728   });
     729 
     730   // Indexes the object's values by a criterion, similar to `groupBy`, but for
     731   // when you know that your index values will be unique.
     732   _.indexBy = group(function(result, value, key) {
     733     // key 值必须是独一无二的
     734     // 不然后面的会覆盖前面的
     735     // 其他和 _.groupBy 类似
     736     result[key] = value;
     737   });
     738 
     739   // Counts instances of an object that group by a certain criterion. Pass
     740   // either a string attribute to count by, or a function that returns the
     741   // criterion.
     742   _.countBy = group(function(result, value, key) {
     743     // 不同 key 值元素数量
     744     if (_.has(result, key))
     745       result[key]++;
     746     else result[key] = 1;
     747   });
     748 
     749   // Safely create a real, live array from anything iterable.
     750   // 伪数组 -> 数组
     751   // 对象 -> 提取 value 值组成数组
     752   // 返回数组
     753   _.toArray = function(obj) {
     754     if (!obj) return [];
     755 
     756     // 如果是数组,则返回副本数组
     757     // 是否用 obj.concat() 更方便?
     758     if (_.isArray(obj)) return slice.call(obj);
     759 
     760     // 如果是类数组,则重新构造新的数组
     761     // 是否也可以直接用 slice 方法?
     762     if (isArrayLike(obj)) return _.map(obj, _.identity);
     763 
     764     // 如果是对象,则返回 values 集合
     765     return _.values(obj);
     766   };
     767 
     768   // Return the number of elements in an object.
     769   // 如果是数组(类数组),返回长度(length 属性)
     770   // 如果是对象,返回键值对数量
     771   _.size = function(obj) {
     772     if (obj == null) return 0;
     773     return isArrayLike(obj) ? obj.length : _.keys(obj).length;
     774   };
     775 
     776   // Split a collection into two arrays: one whose elements all satisfy the given
     777   // predicate, and one whose elements all do not satisfy the predicate.
     778   // 将数组或者对象中符合条件(predicate)的元素
     779   // 和不符合条件的元素(数组为元素,对象为 value 值)
     780   // 分别放入两个数组中
     781   // 返回一个数组,数组元素为以上两个数组([[pass array], [fail array]])
     782   _.partition = function(obj, predicate, context) {
     783     predicate = cb(predicate, context);
     784     var pass = [], fail = [];
     785     _.each(obj, function(value, key, obj) {
     786       (predicate(value, key, obj) ? pass : fail).push(value);
     787     });
     788     return [pass, fail];
     789   };
     790 
     791 
     792   // Array Functions
     793   // 数组的扩展方法
     794   // 共 20 个扩展方法
     795   // Note: All array functions will also work on the arguments object.
     796   // However, Underscore functions are not designed to work on "sparse" arrays.
     797   // ---------------
     798 
     799   // Get the first element of an array. Passing **n** will return the first N
     800   // values in the array. Aliased as `head` and `take`. The **guard** check
     801   // allows it to work with `_.map`.
     802   // 返回数组第一个元素
     803   // 如果有参数 n,则返回数组前 n 个元素(组成的数组)
     804   _.first = _.head = _.take = function(array, n, guard) {
     805     // 容错,数组为空则返回 undefined
     806     if (array == null) return void 0;
     807 
     808     // 没指定参数 n,则默认返回第一个元素
     809     if (n == null || guard) return array[0];
     810 
     811     // 如果传入参数 n,则返回前 n 个元素组成的数组
     812     // 返回前 n 个元素,即剔除后 array.length - n 个元素
     813     return _.initial(array, array.length - n);
     814   };
     815 
     816   // Returns everything but the last entry of the array. Especially useful on
     817   // the arguments object. Passing **n** will return all the values in
     818   // the array, excluding the last N.
     819   // 传入一个数组
     820   // 返回剔除最后一个元素之后的数组副本
     821   // 如果传入参数 n,则剔除最后 n 个元素
     822   _.initial = function(array, n, guard) {
     823     return slice.call(array, 0, Math.max(0, array.length - (n == null || guard ? 1 : n)));
     824   };
     825 
     826   // Get the last element of an array. Passing **n** will return the last N
     827   // values in the array.
     828   // 返回数组最后一个元素
     829   // 如果传入参数 n
     830   // 则返回该数组后 n 个元素组成的数组
     831   // 即剔除前 array.length - n 个元素
     832   _.last = function(array, n, guard) {
     833     // 容错
     834     if (array == null) return void 0;
     835 
     836     // 如果没有指定参数 n,则返回最后一个元素
     837     if (n == null || guard) return array[array.length - 1];
     838 
     839     // 如果传入参数 n,则返回后 n 个元素组成的数组
     840     // 即剔除前 array.length - n 个元素
     841     return _.rest(array, Math.max(0, array.length - n));
     842   };
     843 
     844   // Returns everything but the first entry of the array. Aliased as `tail` and `drop`.
     845   // Especially useful on the arguments object. Passing an **n** will return
     846   // the rest N values in the array.
     847   // 传入一个数组
     848   // 返回剔除第一个元素后的数组副本
     849   // 如果传入参数 n,则剔除前 n 个元素
     850   _.rest = _.tail = _.drop = function(array, n, guard) {
     851     return slice.call(array, n == null || guard ? 1 : n);
     852   };
     853 
     854   // Trim out all falsy values from an array.
     855   // 去掉数组中所有的假值
     856   // 返回数组副本
     857   // JavaScript 中的假值包括 false、null、undefined、''、NaN、0
     858   // 联想 PHP 中的 array_filter() 函数
     859   // _.identity = function(value) {
     860   //   return value;
     861   // };
     862   _.compact = function(array) {
     863     return _.filter(array, _.identity);
     864   };
     865 
     866   // Internal implementation of a recursive `flatten` function.
     867   // 递归调用数组,将数组展开
     868   // 即 [1, 2, [3, 4]] => [1, 2, 3, 4]
     869   // flatten(array, shallow, false)
     870   // flatten(arguments, true, true, 1)
     871   // flatten(arguments, true, true)
     872   // flatten(arguments, false, false, 1)
     873   // ===== //
     874   // input => Array 或者 arguments
     875   // shallow => 是否只展开一层
     876   // strict === true,通常和 shallow === true 配合使用
     877   // 表示只展开一层,但是不保存非数组元素(即无法展开的基础类型)
     878   // flatten([[1, 2], 3, 4], true, true) => [1, 2]
     879   // flatten([[1, 2], 3, 4], false, true) = > []
     880   // startIndex => 从 input 的第几项开始展开
     881   // ===== //
     882   // 可以看到,如果 strict 参数为 true,那么 shallow 也为 true
     883   // 也就是展开一层,同时把非数组过滤
     884   // [[1, 2], [3, 4], 5, 6] => [1, 2, 3, 4]
     885   var flatten = function(input, shallow, strict, startIndex) {
     886     // output 数组保存结果
     887     // 即 flatten 方法返回数据
     888     // idx 为 output 的累计数组下标
     889     var output = [], idx = 0;
     890 
     891     // 根据 startIndex 变量确定需要展开的起始位置
     892     for (var i = startIndex || 0, length = getLength(input); i < length; i++) {
     893       var value = input[i];
     894       // 数组 或者 arguments
     895       // 注意 isArrayLike 还包括 {length: 10} 这样的,过滤掉
     896       if (isArrayLike(value) && (_.isArray(value) || _.isArguments(value))) {
     897         // flatten current level of array or arguments object
     898         // (!shallow === true) => (shallow === false)
     899         // 则表示需深度展开
     900         // 继续递归展开
     901         if (!shallow)
     902           // flatten 方法返回数组
     903           // 将上面定义的 value 重新赋值
     904           value = flatten(value, shallow, strict);
     905 
     906         // 递归展开到最后一层(没有嵌套的数组了)
     907         // 或者 (shallow === true) => 只展开一层
     908         // value 值肯定是一个数组
     909         var j = 0, len = value.length;
     910 
     911         // 这一步貌似没有必要
     912         // 毕竟 JavaScript 的数组会自动扩充
     913         // 但是这样写,感觉比较好,对于元素的 push 过程有个比较清晰的认识
     914         output.length += len;
     915 
     916         // 将 value 数组的元素添加到 output 数组中
     917         while (j < len) {
     918           output[idx++] = value[j++];
     919         }
     920       } else if (!strict) {
     921         // (!strict === true) => (strict === false)
     922         // 如果是深度展开,即 shallow 参数为 false
     923         // 那么当最后 value 不是数组,是基本类型时
     924         // 肯定会走到这个 else-if 判断中
     925         // 而如果此时 strict 为 true,则不能跳到这个分支内部
     926         // 所以 shallow === false 如果和 strict === true 搭配
     927         // 调用 flatten 方法得到的结果永远是空数组 []
     928         output[idx++] = value;
     929       }
     930     }
     931 
     932     return output;
     933   };
     934 
     935   // Flatten out an array, either recursively (by default), or just one level.
     936   // 将嵌套的数组展开
     937   // 如果参数 (shallow === true),则仅展开一层
     938   // _.flatten([1, [2], [3, [[4]]]]);
     939   // => [1, 2, 3, 4];
     940   // ====== //
     941   // _.flatten([1, [2], [3, [[4]]]], true);
     942   // => [1, 2, 3, [[4]]];
     943   _.flatten = function(array, shallow) {
     944     // array => 需要展开的数组
     945     // shallow => 是否只展开一层
     946     // false 为 flatten 方法 strict 变量
     947     return flatten(array, shallow, false);
     948   };
     949 
     950   // Return a version of the array that does not contain the specified value(s).
     951   // without_.without(array, *values)
     952   // Returns a copy of the array with all instances of the values removed.
     953   // ====== //
     954   // _.without([1, 2, 1, 0, 3, 1, 4], 0, 1);
     955   // => [2, 3, 4]
     956   // ===== //
     957   // 从数组中移除指定的元素
     958   // 返回移除后的数组副本
     959   _.without = function(array) {
     960     // slice.call(arguments, 1)
     961     // 将 arguments 转为数组(同时去掉第一个元素)
     962     // 之后便可以调用 _.difference 方法
     963     return _.difference(array, slice.call(arguments, 1));
     964   };
     965 
     966   // Produce a duplicate-free version of the array. If the array has already
     967   // been sorted, you have the option of using a faster algorithm.
     968   // Aliased as `unique`.
     969   // 数组去重
     970   // 如果第二个参数 `isSorted` 为 true
     971   // 则说明事先已经知道数组有序
     972   // 程序会跑一个更快的算法(一次线性比较,元素和数组前一个元素比较即可)
     973   // 如果有第三个参数 iteratee,则对数组每个元素迭代
     974   // 对迭代之后的结果进行去重
     975   // 返回去重后的数组(array 的子数组)
     976   // PS: 暴露的 API 中没 context 参数
     977   // _.uniq(array, [isSorted], [iteratee])
     978   _.uniq = _.unique = function(array, isSorted, iteratee, context) {
     979     // 没有传入 isSorted 参数
     980     // 转为 _.unique(array, false, undefined, iteratee)
     981     if (!_.isBoolean(isSorted)) {
     982       context = iteratee;
     983       iteratee = isSorted;
     984       isSorted = false;
     985     }
     986 
     987     // 如果有迭代函数
     988     // 则根据 this 指向二次返回新的迭代函数
     989     if (iteratee != null)
     990       iteratee = cb(iteratee, context);
     991 
     992     // 结果数组,是 array 的子集
     993     var result = [];
     994 
     995     // 已经出现过的元素(或者经过迭代过的值)
     996     // 用来过滤重复值
     997     var seen = [];
     998 
     999     for (var i = 0, length = getLength(array); i < length; i++) {
    1000       var value = array[i],
    1001           // 如果指定了迭代函数
    1002           // 则对数组每一个元素进行迭代
    1003           // 迭代函数传入的三个参数通常是 value, index, array 形式
    1004           computed = iteratee ? iteratee(value, i, array) : value;
    1005 
    1006       // 如果是有序数组,则当前元素只需跟上一个元素对比即可
    1007       // 用 seen 变量保存上一个元素
    1008       if (isSorted) {
    1009         // 如果 i === 0,是第一个元素,则直接 push
    1010         // 否则比较当前元素是否和前一个元素相等
    1011         if (!i || seen !== computed) result.push(value);
    1012         // seen 保存当前元素,供下一次对比
    1013         seen = computed;
    1014       } else if (iteratee) {
    1015         // 如果 seen[] 中没有 computed 这个元素值
    1016         if (!_.contains(seen, computed)) {
    1017           seen.push(computed);
    1018           result.push(value);
    1019         }
    1020       } else if (!_.contains(result, value)) {
    1021         // 如果不用经过迭代函数计算,也就不用 seen[] 变量了
    1022         result.push(value);
    1023       }
    1024     }
    1025 
    1026     return result;
    1027   };
    1028 
    1029   // Produce an array that contains the union: each distinct element from all of
    1030   // the passed-in arrays.
    1031   // union_.union(*arrays)
    1032   // Computes the union of the passed-in arrays:
    1033   // the list of unique items, in order, that are present in one or more of the arrays.
    1034   // ========== //
    1035   // _.union([1, 2, 3], [101, 2, 1, 10], [2, 1]);
    1036   // => [1, 2, 3, 101, 10]
    1037   // ========== //
    1038   // 将多个数组的元素集中到一个数组中
    1039   // 并且去重,返回数组副本
    1040   _.union = function() {
    1041     // 首先用 flatten 方法将传入的数组展开成一个数组
    1042     // 然后就可以愉快地调用 _.uniq 方法了
    1043     // 假设 _.union([1, 2, 3], [101, 2, 1, 10], [2, 1]);
    1044     // arguments 为 [[1, 2, 3], [101, 2, 1, 10], [2, 1]]
    1045     // shallow 参数为 true,展开一层
    1046     // 结果为 [1, 2, 3, 101, 2, 1, 10, 2, 1]
    1047     // 然后对其去重
    1048     return _.uniq(flatten(arguments, true, true));
    1049   };
    1050 
    1051   // Produce an array that contains every item shared between all the
    1052   // passed-in arrays.
    1053   // 寻找几个数组中共有的元素
    1054   // 将这些每个数组中都有的元素存入另一个数组中返回
    1055   // _.intersection(*arrays)
    1056   // _.intersection([1, 2, 3, 1], [101, 2, 1, 10, 1], [2, 1, 1])
    1057   // => [1, 2]
    1058   // 注意:返回的结果数组是去重的
    1059   _.intersection = function(array) {
    1060     // 结果数组
    1061     var result = [];
    1062 
    1063     // 传入的参数(数组)个数
    1064     var argsLength = arguments.length;
    1065 
    1066      // 遍历第一个数组的元素
    1067     for (var i = 0, length = getLength(array); i < length; i++) {
    1068       var item = array[i];
    1069 
    1070       // 如果 result[] 中已经有 item 元素了,continue
    1071       // 即 array 中出现了相同的元素
    1072       // 返回的 result[] 其实是个 "集合"(是去重的)
    1073       if (_.contains(result, item)) continue;
    1074 
    1075       // 判断其他参数数组中是否都有 item 这个元素
    1076       for (var j = 1; j < argsLength; j++) {
    1077         if (!_.contains(arguments[j], item))
    1078           break;
    1079       }
    1080 
    1081       // 遍历其他参数数组完毕
    1082       // j === argsLength 说明其他参数数组中都有 item 元素
    1083       // 则将其放入 result[] 中
    1084       if (j === argsLength)
    1085         result.push(item);
    1086     }
    1087 
    1088     return result;
    1089   };
    1090 
    1091   // Take the difference between one array and a number of other arrays.
    1092   // Only the elements present in just the first array will remain.
    1093   // _.difference(array, *others)
    1094   // Similar to without, but returns the values from array that are not present in the other arrays.
    1095   // ===== //
    1096   // _.difference([1, 2, 3, 4, 5], [5, 2, 10]);
    1097   // => [1, 3, 4]
    1098   // ===== //
    1099   // 剔除 array 数组中在 others 数组中出现的元素
    1100   _.difference = function(array) {
    1101     // 将 others 数组展开一层
    1102     // rest[] 保存展开后的元素组成的数组
    1103     // strict 参数为 true
    1104     // 不可以这样用 _.difference([1, 2, 3, 4, 5], [5, 2], 10);
    1105     // 10 就会取不到
    1106     var rest = flatten(arguments, true, true, 1);
    1107 
    1108     // 遍历 array,过滤
    1109     return _.filter(array, function(value){
    1110       // 如果 value 存在在 rest 中,则过滤掉
    1111       return !_.contains(rest, value);
    1112     });
    1113   };
    1114 
    1115   // Zip together multiple lists into a single array -- elements that share
    1116   // an index go together.
    1117   // ===== //
    1118   // _.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]);
    1119   // => [["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]
    1120   // ===== //
    1121   // 将多个数组中相同位置的元素归类
    1122   // 返回一个数组
    1123   _.zip = function() {
    1124     return _.unzip(arguments);
    1125   };
    1126 
    1127   // Complement of _.zip. Unzip accepts an array of arrays and groups
    1128   // each array's elements on shared indices
    1129   // The opposite of zip. Given an array of arrays,
    1130   // returns a series of new arrays,
    1131   // the first of which contains all of the first elements in the input arrays,
    1132   // the second of which contains all of the second elements, and so on.
    1133   // ===== //
    1134   // _.unzip([["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]);
    1135   // => [['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]]
    1136   // ===== //
    1137   _.unzip = function(array) {
    1138     var length = array && _.max(array, getLength).length || 0;
    1139     var result = Array(length);
    1140 
    1141     for (var index = 0; index < length; index++) {
    1142       result[index] = _.pluck(array, index);
    1143     }
    1144     return result;
    1145   };
    1146 
    1147   // Converts lists into objects. Pass either a single array of `[key, value]`
    1148   // pairs, or two parallel arrays of the same length -- one of keys, and one of
    1149   // the corresponding values.
    1150   // 将数组转化为对象
    1151   _.object = function(list, values) {
    1152     var result = {};
    1153     for (var i = 0, length = getLength(list); i < length; i++) {
    1154       if (values) {
    1155         result[list[i]] = values[i];
    1156       } else {
    1157         result[list[i][0]] = list[i][1];
    1158       }
    1159     }
    1160     return result;
    1161   };
    1162 
    1163   // Generator function to create the findIndex and findLastIndex functions
    1164   // (dir === 1) => 从前往后找
    1165   // (dir === -1) => 从后往前找
    1166   function createPredicateIndexFinder(dir) {
    1167     // 经典闭包
    1168     return function(array, predicate, context) {
    1169       predicate = cb(predicate, context);
    1170 
    1171       var length = getLength(array);
    1172 
    1173       // 根据 dir 变量来确定数组遍历的起始位置
    1174       var index = dir > 0 ? 0 : length - 1;
    1175 
    1176       for (; index >= 0 && index < length; index += dir) {
    1177         // 找到第一个符合条件的元素
    1178         // 并返回下标值
    1179         if (predicate(array[index], index, array))
    1180           return index;
    1181       }
    1182 
    1183       return -1;
    1184     };
    1185   }
    1186 
    1187   // Returns the first index on an array-like that passes a predicate test
    1188   // 从前往后找到数组中 `第一个满足条件` 的元素,并返回下标值
    1189   // 没找到返回 -1
    1190   // _.findIndex(array, predicate, [context])
    1191   _.findIndex = createPredicateIndexFinder(1);
    1192 
    1193   // 从后往前找到数组中 `第一个满足条件` 的元素,并返回下标值
    1194   // 没找到返回 -1
    1195   // _.findLastIndex(array, predicate, [context])
    1196   _.findLastIndex = createPredicateIndexFinder(-1);
    1197 
    1198   // Use a comparator function to figure out the smallest index at which
    1199   // an object should be inserted so as to maintain order. Uses binary search.
    1200   // The iteratee may also be the string name of the property to sort by (eg. length).
    1201   // ===== //
    1202   // _.sortedIndex([10, 20, 30, 40, 50], 35);
    1203   // => 3
    1204   // ===== //
    1205   // var stooges = [{name: 'moe', age: 40}, {name: 'curly', age: 60}];
    1206   // _.sortedIndex(stooges, {name: 'larry', age: 50}, 'age');
    1207   // => 1
    1208   // ===== //
    1209   // 二分查找
    1210   // 将一个元素插入已排序的数组
    1211   // 返回该插入的位置下标
    1212   // _.sortedIndex(list, value, [iteratee], [context])
    1213   _.sortedIndex = function(array, obj, iteratee, context) {
    1214     // 注意 cb 方法
    1215     // iteratee 为空 || 为 String 类型(key 值)时会返回不同方法
    1216     iteratee = cb(iteratee, context, 1);
    1217 
    1218     // 经过迭代函数计算的值
    1219     // 可打印 iteratee 出来看看
    1220     var value = iteratee(obj);
    1221 
    1222     var low = 0, high = getLength(array);
    1223 
    1224     // 二分查找
    1225     while (low < high) {
    1226       var mid = Math.floor((low + high) / 2);
    1227       if (iteratee(array[mid]) < value)
    1228         low = mid + 1;
    1229       else
    1230         high = mid;
    1231     }
    1232 
    1233     return low;
    1234   };
    1235 
    1236   // Generator function to create the indexOf and lastIndexOf functions
    1237   // _.indexOf = createIndexFinder(1, _.findIndex, _.sortedIndex);
    1238   // _.lastIndexOf = createIndexFinder(-1, _.findLastIndex);
    1239   function createIndexFinder(dir, predicateFind, sortedIndex) {
    1240     // API 调用形式
    1241     // _.indexOf(array, value, [isSorted])
    1242     // _.indexOf(array, value, [fromIndex])
    1243     // _.lastIndexOf(array, value, [fromIndex])
    1244     return function(array, item, idx) {
    1245       var i = 0, length = getLength(array);
    1246 
    1247       // 如果 idx 为 Number 类型
    1248       // 则规定查找位置的起始点
    1249       // 那么第三个参数不是 [isSorted]
    1250       // 所以不能用二分查找优化了
    1251       // 只能遍历查找
    1252       if (typeof idx == 'number') {
    1253         if (dir > 0) { // 正向查找
    1254           // 重置查找的起始位置
    1255           i = idx >= 0 ? idx : Math.max(idx + length, i);
    1256         } else { // 反向查找
    1257           // 如果是反向查找,重置 length 属性值
    1258           length = idx >= 0 ? Math.min(idx + 1, length) : idx + length + 1;
    1259         }
    1260       } else if (sortedIndex && idx && length) {
    1261         // 能用二分查找加速的条件
    1262         // 有序 & idx !== 0 && length !== 0
    1263 
    1264         // 用 _.sortIndex 找到有序数组中 item 正好插入的位置
    1265         idx = sortedIndex(array, item);
    1266 
    1267         // 如果正好插入的位置的值和 item 刚好相等
    1268         // 说明该位置就是 item 第一次出现的位置
    1269         // 返回下标
    1270         // 否则即是没找到,返回 -1
    1271         return array[idx] === item ? idx : -1;
    1272       }
    1273 
    1274       // 特判,如果要查找的元素是 NaN 类型
    1275       // 如果 item !== item
    1276       // 那么 item => NaN
    1277       if (item !== item) {
    1278         idx = predicateFind(slice.call(array, i, length), _.isNaN);
    1279         return idx >= 0 ? idx + i : -1;
    1280       }
    1281 
    1282       // O(n) 遍历数组
    1283       // 寻找和 item 相同的元素
    1284       // 特判排除了 item 为 NaN 的情况
    1285       // 可以放心地用 `===` 来判断是否相等了
    1286       for (idx = dir > 0 ? i : length - 1; idx >= 0 && idx < length; idx += dir) {
    1287         if (array[idx] === item) return idx;
    1288       }
    1289 
    1290       return -1;
    1291     };
    1292   }
    1293 
    1294   // Return the position of the first occurrence of an item in an array,
    1295   // or -1 if the item is not included in the array.
    1296   // If the array is large and already in sort order, pass `true`
    1297   // for **isSorted** to use binary search.
    1298   // _.indexOf(array, value, [isSorted])
    1299   // 找到数组 array 中 value 第一次出现的位置
    1300   // 并返回其下标值
    1301   // 如果数组有序,则第三个参数可以传入 true
    1302   // 这样算法效率会更高(二分查找)
    1303   // [isSorted] 参数表示数组是否有序
    1304   // 同时第三个参数也可以表示 [fromIndex] (见下面的 _.lastIndexOf)
    1305   _.indexOf = createIndexFinder(1, _.findIndex, _.sortedIndex);
    1306 
    1307   // 和 _indexOf 相似
    1308   // 反序查找
    1309   // _.lastIndexOf(array, value, [fromIndex])
    1310   // [fromIndex] 参数表示从倒数第几个开始往前找
    1311   _.lastIndexOf = createIndexFinder(-1, _.findLastIndex);
    1312 
    1313   // Generate an integer Array containing an arithmetic progression. A port of
    1314   // the native Python `range()` function. See
    1315   // [the Python documentation](http://docs.python.org/library/functions.html#range).
    1316   // 返回某一个范围内的数组成的数组
    1317   _.range = function(start, stop, step) {
    1318     if (stop == null) {
    1319       stop = start || 0;
    1320       start = 0;
    1321     }
    1322 
    1323     step = step || 1;
    1324 
    1325     // 返回数组的长度
    1326     var length = Math.max(Math.ceil((stop - start) / step), 0);
    1327 
    1328     // 返回的数组
    1329     var range = Array(length);
    1330 
    1331     for (var idx = 0; idx < length; idx++, start += step) {
    1332       range[idx] = start;
    1333     }
    1334 
    1335     return range;
    1336   };
    1337 
    1338 
    1339   // Function (ahem) Functions
    1340   // 函数的扩展方法
    1341   // 共 14 个扩展方法
    1342   // ------------------
    1343 
    1344   // Determines whether to execute a function as a constructor
    1345   // or a normal function with the provided arguments
    1346   var executeBound = function(sourceFunc, boundFunc, context, callingContext, args) {
    1347     // 非 new 调用 _.bind 返回的方法(即 bound)
    1348     // callingContext 不是 boundFunc 的一个实例
    1349     if (!(callingContext instanceof boundFunc))
    1350       return sourceFunc.apply(context, args);
    1351 
    1352     // 如果是用 new 调用 _.bind 返回的方法
    1353 
    1354     // self 为 sourceFunc 的实例,继承了它的原型链
    1355     // self 理论上是一个空对象(还没赋值),但是有原型链
    1356     var self = baseCreate(sourceFunc.prototype);
    1357 
    1358     // 用 new 生成一个构造函数的实例
    1359     // 正常情况下是没有返回值的,即 result 值为 undefined
    1360     // 如果构造函数有返回值
    1361     // 如果返回值是对象(非 null),则 new 的结果返回这个对象
    1362     // 否则返回实例
    1363     // @see http://www.cnblogs.com/zichi/p/4392944.html
    1364     var result = sourceFunc.apply(self, args);
    1365 
    1366     // 如果构造函数返回了对象
    1367     // 则 new 的结果是这个对象
    1368     // 返回这个对象
    1369     if (_.isObject(result)) return result;
    1370 
    1371     // 否则返回 self
    1372     // var result = sourceFunc.apply(self, args);
    1373     // self 对象当做参数传入
    1374     // 会直接改变值
    1375     return self;
    1376   };
    1377 
    1378   // Create a function bound to a given object (assigning `this`, and arguments,
    1379   // optionally). Delegates to **ECMAScript 5**'s native `Function.bind` if
    1380   // available.
    1381   // ES5 bind 方法的扩展(polyfill)
    1382   // 将 func 中的 this 指向 context(对象)
    1383   // _.bind(function, object, *arguments)
    1384   // 可选的 arguments 参数会被当作 func 的参数传入
    1385   // func 在调用时,会优先用 arguments 参数,然后使用 _.bind 返回方法所传入的参数
    1386   _.bind = function(func, context) {
    1387     // 如果浏览器支持 ES5 bind 方法,并且 func 上的 bind 方法没有被重写
    1388     // 则优先使用原生的 bind 方法
    1389     if (nativeBind && func.bind === nativeBind)
    1390       return nativeBind.apply(func, slice.call(arguments, 1));
    1391 
    1392     // 如果传入的参数 func 不是方法,则抛出错误
    1393     if (!_.isFunction(func))
    1394       throw new TypeError('Bind must be called on a function');
    1395 
    1396     // polyfill
    1397     // 经典闭包,函数返回函数
    1398     // args 获取优先使用的参数
    1399     var args = slice.call(arguments, 2);
    1400     var bound = function() {
    1401       // args.concat(slice.call(arguments))
    1402       // 最终函数的实际调用参数由两部分组成
    1403       // 一部分是传入 _.bind 的参数(会被优先调用)
    1404       // 另一部分是传入 bound(_.bind 所返回方法)的参数
    1405       return executeBound(func, bound, context, this, args.concat(slice.call(arguments)));
    1406     };
    1407 
    1408     return bound;
    1409   };
    1410 
    1411   // Partially apply a function by creating a version that has had some of its
    1412   // arguments pre-filled, without changing its dynamic `this` context. _ acts
    1413   // as a placeholder, allowing any combination of arguments to be pre-filled.
    1414   // _.partial(function, *arguments)
    1415   // _.partial 能返回一个方法
    1416   // pre-fill 该方法的一些参数
    1417   _.partial = function(func) {
    1418     // 提取希望 pre-fill 的参数
    1419     // 如果传入的是 _,则这个位置的参数暂时空着,等待手动填入
    1420     var boundArgs = slice.call(arguments, 1);
    1421 
    1422     var bound = function() {
    1423       var position = 0, length = boundArgs.length;
    1424       var args = Array(length);
    1425       for (var i = 0; i < length; i++) {
    1426         // 如果该位置的参数为 _,则用 bound 方法的参数填充这个位置
    1427         // args 为调用 _.partial 方法的 pre-fill 的参数 & bound 方法的 arguments
    1428         args[i] = boundArgs[i] === _ ? arguments[position++] : boundArgs[i];
    1429       }
    1430 
    1431       // bound 方法还有剩余的 arguments,添上去
    1432       while (position < arguments.length)
    1433         args.push(arguments[position++]);
    1434 
    1435       return executeBound(func, bound, this, this, args);
    1436     };
    1437 
    1438     return bound;
    1439   };
    1440 
    1441   // Bind a number of an object's methods to that object. Remaining arguments
    1442   // are the method names to be bound. Useful for ensuring that all callbacks
    1443   // defined on an object belong to it.
    1444   // 指定一系列方法(methodNames)中的 this 指向(object)
    1445   // _.bindAll(object, *methodNames)
    1446   _.bindAll = function(obj) {
    1447     var i, length = arguments.length, key;
    1448 
    1449     // 如果只传入了一个参数(obj),没有传入 methodNames,则报错
    1450     if (length <= 1)
    1451       throw new Error('bindAll must be passed function names');
    1452 
    1453     // 遍历 methodNames
    1454     for (i = 1; i < length; i++) {
    1455       key = arguments[i];
    1456       // 逐个绑定
    1457       obj[key] = _.bind(obj[key], obj);
    1458     }
    1459     return obj;
    1460   };
    1461 
    1462   // Memoize an expensive function by storing its results.
    1463   //「记忆化」,存储中间运算结果,提高效率
    1464   // 参数 hasher 是个 function,用来计算 key
    1465   // 如果传入了 hasher,则用 hasher 来计算 key
    1466   // 否则用 key 参数直接当 key(即 memoize 方法传入的第一个参数)
    1467   // _.memoize(function, [hashFunction])
    1468   // 适用于需要大量重复求值的场景
    1469   // 比如递归求解菲波那切数
    1470   // @http://www.jameskrob.com/memoize.html
    1471   // create hash for storing "expensive" function outputs
    1472   // run expensive function
    1473   // check whether function has already been run with given arguments via hash lookup
    1474   // if false - run function, and store output in hash
    1475   // if true, return output stored in hash
    1476   _.memoize = function(func, hasher) {
    1477     var memoize = function(key) {
    1478       // 储存变量,方便使用
    1479       var cache = memoize.cache;
    1480 
    1481       // 求 key
    1482       // 如果传入了 hasher,则用 hasher 函数来计算 key
    1483       // 否则用 参数 key(即 memoize 方法传入的第一个参数)当 key
    1484       var address = '' + (hasher ? hasher.apply(this, arguments) : key);
    1485 
    1486       // 如果这个 key 还没被 hash 过(还没求过值)
    1487       if (!_.has(cache, address))
    1488         cache[address] = func.apply(this, arguments);
    1489 
    1490       // 返回
    1491       return cache[address];
    1492     };
    1493 
    1494     // cache 对象被当做 key-value 键值对缓存中间运算结果
    1495     memoize.cache = {};
    1496 
    1497     // 返回一个函数(经典闭包)
    1498     return memoize;
    1499   };
    1500 
    1501   // Delays a function for the given number of milliseconds, and then calls
    1502   // it with the arguments supplied.
    1503   // 延迟触发某方法
    1504   // _.delay(function, wait, *arguments)
    1505   //  如果传入了 arguments 参数,则会被当作 func 的参数在触发时调用
    1506   // 其实是封装了「延迟触发某方法」,使其复用
    1507   _.delay = function(func, wait) {
    1508     // 获取 *arguments
    1509     // 是 func 函数所需要的参数
    1510     var args = slice.call(arguments, 2);
    1511     return setTimeout(function(){
    1512       // 将参数赋予 func 函数
    1513       return func.apply(null, args);
    1514     }, wait);
    1515   };
    1516 
    1517   // Defers a function, scheduling it to run after the current call stack has
    1518   // cleared.
    1519   // 和 setTimeout(func, 0) 相似(源码看来似乎应该是 setTimeout(func, 1))
    1520   // _.defer(function, *arguments)
    1521   // 如果传入 *arguments,会被当做参数,和 _.delay 调用方式类似(少了第二个参数)
    1522   // 其实核心还是调用了 _.delay 方法,但第二个参数(wait 参数)设置了默认值为 1
    1523   // 如何使得方法能设置默认值?用 _.partial 方法
    1524   _.defer = _.partial(_.delay, _, 1);
    1525 
    1526   // Returns a function, that, when invoked, will only be triggered at most once
    1527   // during a given window of time. Normally, the throttled function will run
    1528   // as much as it can, without ever going more than once per `wait` duration;
    1529   // but if you'd like to disable the execution on the leading edge, pass
    1530   // `{leading: false}`. To disable execution on the trailing edge, ditto.
    1531   // 函数节流(如果有连续事件响应,则每间隔一定时间段触发)
    1532   // 每间隔 wait(Number) milliseconds 触发一次 func 方法
    1533   // 如果 options 参数传入 {leading: false}
    1534   // 那么不会马上触发(等待 wait milliseconds 后第一次触发 func)
    1535   // 如果 options 参数传入 {trailing: false}
    1536   // 那么最后一次回调不会被触发
    1537   // **Notice: options 不能同时设置 leading 和 trailing 为 false**
    1538   // 示例:
    1539   // var throttled = _.throttle(updatePosition, 100);
    1540   // $(window).scroll(throttled);
    1541   // 调用方式(注意看 A 和 B console.log 打印的位置):
    1542   // _.throttle(function, wait, [options])
    1543   // sample 1: _.throttle(function(){}, 1000)
    1544   // print: A, B, B, B ...
    1545   // sample 2: _.throttle(function(){}, 1000, {leading: false})
    1546   // print: B, B, B, B ...
    1547   // sample 3: _.throttle(function(){}, 1000, {trailing: false})
    1548   // print: A, A, A, A ...
    1549   // ----------------------------------------- //
    1550   _.throttle = function(func, wait, options) {
    1551     var context, args, result;
    1552 
    1553     // setTimeout 的 handler
    1554     var timeout = null;
    1555 
    1556     // 标记时间戳
    1557     // 上一次执行回调的时间戳
    1558     var previous = 0;
    1559 
    1560     // 如果没有传入 options 参数
    1561     // 则将 options 参数置为空对象
    1562     if (!options)
    1563       options = {};
    1564 
    1565     var later = function() {
    1566       // 如果 options.leading === false
    1567       // 则每次触发回调后将 previous 置为 0
    1568       // 否则置为当前时间戳
    1569       previous = options.leading === false ? 0 : _.now();
    1570       timeout = null;
    1571       // console.log('B')
    1572       result = func.apply(context, args);
    1573 
    1574       // 这里的 timeout 变量一定是 null 了吧
    1575       // 是否没有必要进行判断?
    1576       if (!timeout)
    1577         context = args = null;
    1578     };
    1579 
    1580     // 以滚轮事件为例(scroll)
    1581     // 每次触发滚轮事件即执行这个返回的方法
    1582     // _.throttle 方法返回的函数
    1583     return function() {
    1584       // 记录当前时间戳
    1585       var now = _.now();
    1586 
    1587       // 第一次执行回调(此时 previous 为 0,之后 previous 值为上一次时间戳)
    1588       // 并且如果程序设定第一个回调不是立即执行的(options.leading === false)
    1589       // 则将 previous 值(表示上次执行的时间戳)设为 now 的时间戳(第一次触发时)
    1590       // 表示刚执行过,这次就不用执行了
    1591       if (!previous && options.leading === false)
    1592         previous = now;
    1593 
    1594       // 距离下次触发 func 还需要等待的时间
    1595       var remaining = wait - (now - previous);
    1596       context = this;
    1597       args = arguments;
    1598 
    1599       // 要么是到了间隔时间了,随即触发方法(remaining <= 0)
    1600       // 要么是没有传入 {leading: false},且第一次触发回调,即立即触发
    1601       // 此时 previous 为 0,wait - (now - previous) 也满足 <= 0
    1602       // 之后便会把 previous 值迅速置为 now
    1603       // ========= //
    1604       // remaining > wait,表示客户端系统时间被调整过
    1605       // 则马上执行 func 函数
    1606       // @see https://blog.coding.net/blog/the-difference-between-throttle-and-debounce-in-underscorejs
    1607       // ========= //
    1608 
    1609       // console.log(remaining) 可以打印出来看看
    1610       if (remaining <= 0 || remaining > wait) {
    1611         if (timeout) {
    1612           clearTimeout(timeout);
    1613           // 解除引用,防止内存泄露
    1614           timeout = null;
    1615         }
    1616 
    1617         // 重置前一次触发的时间戳
    1618         previous = now;
    1619 
    1620         // 触发方法
    1621         // result 为该方法返回值
    1622         // console.log('A')
    1623         result = func.apply(context, args);
    1624 
    1625         // 引用置为空,防止内存泄露
    1626         // 感觉这里的 timeout 肯定是 null 啊?这个 if 判断没必要吧?
    1627         if (!timeout)
    1628           context = args = null;
    1629       } else if (!timeout && options.trailing !== false) { // 最后一次需要触发的情况
    1630         // 如果已经存在一个定时器,则不会进入该 if 分支
    1631         // 如果 {trailing: false},即最后一次不需要触发了,也不会进入这个分支
    1632         // 间隔 remaining milliseconds 后触发 later 方法
    1633         timeout = setTimeout(later, remaining);
    1634       }
    1635 
    1636       // 回调返回值
    1637       return result;
    1638     };
    1639   };
    1640 
    1641   // Returns a function, that, as long as it continues to be invoked, will not
    1642   // be triggered. The function will be called after it stops being called for
    1643   // N milliseconds. If `immediate` is passed, trigger the function on the
    1644   // leading edge, instead of the trailing.
    1645   // 函数去抖(连续事件触发结束后只触发一次)
    1646   // sample 1: _.debounce(function(){}, 1000)
    1647   // 连续事件结束后的 1000ms 后触发
    1648   // sample 1: _.debounce(function(){}, 1000, true)
    1649   // 连续事件触发后立即触发(此时会忽略第二个参数)
    1650   _.debounce = function(func, wait, immediate) {
    1651     var timeout, args, context, timestamp, result;
    1652 
    1653     var later = function() {
    1654       // 定时器设置的回调 later 方法的触发时间,和连续事件触发的最后一次时间戳的间隔
    1655       // 如果间隔为 wait(或者刚好大于 wait),则触发事件
    1656       var last = _.now() - timestamp;
    1657 
    1658       // 时间间隔 last 在 [0, wait) 中
    1659       // 还没到触发的点,则继续设置定时器
    1660       // last 值应该不会小于 0 吧?
    1661       if (last < wait && last >= 0) {
    1662         timeout = setTimeout(later, wait - last);
    1663       } else {
    1664         // 到了可以触发的时间点
    1665         timeout = null;
    1666         // 可以触发了
    1667         // 并且不是设置为立即触发的
    1668         // 因为如果是立即触发(callNow),也会进入这个回调中
    1669         // 主要是为了将 timeout 值置为空,使之不影响下次连续事件的触发
    1670         // 如果不是立即执行,随即执行 func 方法
    1671         if (!immediate) {
    1672           // 执行 func 函数
    1673           result = func.apply(context, args);
    1674           // 这里的 timeout 一定是 null 了吧
    1675           // 感觉这个判断多余了
    1676           if (!timeout)
    1677             context = args = null;
    1678         }
    1679       }
    1680     };
    1681 
    1682     // 嗯,闭包返回的函数,是可以传入参数的
    1683     // 也是 DOM 事件所触发的回调函数
    1684     return function() {
    1685       // 可以指定 this 指向
    1686       context = this;
    1687       args = arguments;
    1688 
    1689       // 每次触发函数,更新时间戳
    1690       // later 方法中取 last 值时用到该变量
    1691       // 判断距离上次触发事件是否已经过了 wait seconds 了
    1692       // 即我们需要距离最后一次事件触发 wait seconds 后触发这个回调方法
    1693       timestamp = _.now();
    1694 
    1695       // 立即触发需要满足两个条件
    1696       // immediate 参数为 true,并且 timeout 还没设置
    1697       // immediate 参数为 true 是显而易见的
    1698       // 如果去掉 !timeout 的条件,就会一直触发,而不是触发一次
    1699       // 因为第一次触发后已经设置了 timeout,所以根据 timeout 是否为空可以判断是否是首次触发
    1700       var callNow = immediate && !timeout;
    1701 
    1702       // 设置 wait seconds 后触发 later 方法
    1703       // 无论是否 callNow(如果是 callNow,也进入 later 方法,去 later 方法中判断是否执行相应回调函数)
    1704       // 在某一段的连续触发中,只会在第一次触发时进入这个 if 分支中
    1705       if (!timeout)
    1706         // 设置了 timeout,所以以后不会进入这个 if 分支了
    1707         timeout = setTimeout(later, wait);
    1708 
    1709       // 如果是立即触发
    1710       if (callNow) {
    1711         // func 可能是有返回值的
    1712         result = func.apply(context, args);
    1713         // 解除引用
    1714         context = args = null;
    1715       }
    1716 
    1717       return result;
    1718     };
    1719   };
    1720 
    1721   // Returns the first function passed as an argument to the second,
    1722   // allowing you to adjust arguments, run code before and after, and
    1723   // conditionally execute the original function.
    1724   _.wrap = function(func, wrapper) {
    1725     return _.partial(wrapper, func);
    1726   };
    1727 
    1728   // Returns a negated version of the passed-in predicate.
    1729   // 返回一个 predicate 方法的对立方法
    1730   // 即该方法可以对原来的 predicate 迭代结果值取补集
    1731   _.negate = function(predicate) {
    1732     return function() {
    1733       return !predicate.apply(this, arguments);
    1734     };
    1735   };
    1736 
    1737   // Returns a function that is the composition of a list of functions, each
    1738   // consuming the return value of the function that follows.
    1739   // _.compose(*functions)
    1740   // var tmp = _.compose(f, g, h)
    1741   // tmp(args) => f(g(h(args)))
    1742   _.compose = function() {
    1743     var args = arguments; // funcs
    1744     var start = args.length - 1; // 倒序调用
    1745     return function() {
    1746       var i = start;
    1747       var result = args[start].apply(this, arguments);
    1748       // 一个一个方法地执行
    1749       while (i--)
    1750         result = args[i].call(this, result);
    1751       return result;
    1752     };
    1753   };
    1754 
    1755   // Returns a function that will only be executed on and after the Nth call.
    1756   // 第 times 触发执行 func(事实上之后的每次触发还是会执行 func)
    1757   // 有什么用呢?
    1758   // 如果有 N 个异步事件,所有异步执行完后执行该回调,即 func 方法(联想 eventproxy)
    1759   // _.after 会返回一个函数
    1760   // 当这个函数第 times 被执行的时候
    1761   // 触发 func 方法
    1762   _.after = function(times, func) {
    1763     return function() {
    1764       // 函数被触发了 times 了,则执行 func 函数
    1765       // 事实上 times 次后如果函数继续被执行,也会触发 func
    1766       if (--times < 1) {
    1767         return func.apply(this, arguments);
    1768       }
    1769     };
    1770   };
    1771 
    1772   // Returns a function that will only be executed up to (but not including) the Nth call.
    1773   // 函数至多被调用 times - 1 次((but not including) the Nth call)
    1774   // func 函数会触发 time - 1 次(Creates a version of the function that can be called no more than count times)
    1775   // func 函数有个返回值,前 time - 1 次触发的返回值都是将参数代入重新计算的
    1776   // 第 times 开始的返回值为第 times - 1 次时的返回值(不重新计算)
    1777   // The result of the last function call is memoized and returned when count has been reached.
    1778   _.before = function(times, func) {
    1779     var memo;
    1780     return function() {
    1781       if (--times > 0) {
    1782         // 缓存函数执行结果
    1783         memo = func.apply(this, arguments);
    1784       }
    1785 
    1786       // func 引用置为空,其实不置为空也用不到 func 了
    1787       if (times <= 1)
    1788         func = null;
    1789 
    1790       // 前 times - 1 次触发,memo 都是分别计算返回
    1791       // 第 times 次开始,memo 值同 times - 1 次时的 memo
    1792       return memo;
    1793     };
    1794   };
    1795 
    1796   // Returns a function that will be executed at most one time, no matter how
    1797   // often you call it. Useful for lazy initialization.
    1798   // 函数至多只能被调用一次
    1799   // 适用于这样的场景,某些函数只能被初始化一次,不得不设置一个变量 flag
    1800   // 初始化后设置 flag 为 true,之后不断 check flag
    1801   // ====== //
    1802   // 其实是调用了 _.before 方法,并且将 times 参数设置为了默认值 2(也就是 func 至多能被调用 2 - 1 = 1 次)
    1803   _.once = _.partial(_.before, 2);
    1804 
    1805 
    1806   // Object Functions
    1807   // 对象的扩展方法
    1808   // 共 38 个扩展方法
    1809   // ----------------
    1810 
    1811   // Keys in IE < 9 that won't be iterated by `for key in ...` and thus missed.
    1812   // IE < 9 下 不能用 for key in ... 来枚举对象的某些 key
    1813   // 比如重写了对象的 `toString` 方法,这个 key 值就不能在 IE < 9 下用 for in 枚举到
    1814   // IE < 9,{toString: null}.propertyIsEnumerable('toString') 返回 false
    1815   // IE < 9,重写的 `toString` 属性被认为不可枚举
    1816   // 据此可以判断是否在 IE < 9 浏览器环境中
    1817   var hasEnumBug = !{toString: null}.propertyIsEnumerable('toString');
    1818 
    1819   // IE < 9 下不能用 for in 来枚举的 key 值集合
    1820   // 其实还有个 `constructor` 属性
    1821   // 个人觉得可能是 `constructor` 和其他属性不属于一类
    1822   // nonEnumerableProps[] 中都是方法
    1823   // 而 constructor 表示的是对象的构造函数
    1824   // 所以区分开来了
    1825   var nonEnumerableProps = ['valueOf', 'isPrototypeOf', 'toString',
    1826                       'propertyIsEnumerable', 'hasOwnProperty', 'toLocaleString'];
    1827 
    1828   // obj 为需要遍历键值对的对象
    1829   // keys 为键数组
    1830   // 利用 JavaScript 按值传递的特点
    1831   // 传入数组作为参数,能直接改变数组的值
    1832   function collectNonEnumProps(obj, keys) {
    1833     var nonEnumIdx = nonEnumerableProps.length;
    1834     var constructor = obj.constructor;
    1835 
    1836     // 获取对象的原型
    1837     // 如果 obj 的 constructor 被重写
    1838     // 则 proto 变量为 Object.prototype
    1839     // 如果没有被重写
    1840     // 则为 obj.constructor.prototype
    1841     var proto = (_.isFunction(constructor) && constructor.prototype) || ObjProto;
    1842 
    1843     // Constructor is a special case.
    1844     // `constructor` 属性需要特殊处理 (是否有必要?)
    1845     // see https://github.com/hanzichi/underscore-analysis/issues/3
    1846     // 如果 obj 有 `constructor` 这个 key
    1847     // 并且该 key 没有在 keys 数组中
    1848     // 存入 keys 数组
    1849     var prop = 'constructor';
    1850     if (_.has(obj, prop) && !_.contains(keys, prop)) keys.push(prop);
    1851 
    1852     // 遍历 nonEnumerableProps 数组中的 keys
    1853     while (nonEnumIdx--) {
    1854       prop = nonEnumerableProps[nonEnumIdx];
    1855       // prop in obj 应该肯定返回 true 吧?是否有判断必要?
    1856       // obj[prop] !== proto[prop] 判断该 key 是否来自于原型链
    1857       // 即是否重写了原型链上的属性
    1858       if (prop in obj && obj[prop] !== proto[prop] && !_.contains(keys, prop)) {
    1859         keys.push(prop);
    1860       }
    1861     }
    1862   }
    1863 
    1864   // Retrieve the names of an object's own properties.
    1865   // Delegates to **ECMAScript 5**'s native `Object.keys`
    1866   // ===== //
    1867   // _.keys({one: 1, two: 2, three: 3});
    1868   // => ["one", "two", "three"]
    1869   // ===== //
    1870   // 返回一个对象的 keys 组成的数组
    1871   // 仅返回 own enumerable properties 组成的数组
    1872   _.keys = function(obj) {
    1873     // 容错
    1874     // 如果传入的参数不是对象,则返回空数组
    1875     if (!_.isObject(obj)) return [];
    1876 
    1877     // 如果浏览器支持 ES5 Object.key() 方法
    1878     // 则优先使用该方法
    1879     if (nativeKeys) return nativeKeys(obj);
    1880 
    1881     var keys = [];
    1882 
    1883     // own enumerable properties
    1884     for (var key in obj)
    1885       // hasOwnProperty
    1886       if (_.has(obj, key)) keys.push(key);
    1887 
    1888     // Ahem, IE < 9.
    1889     // IE < 9 下不能用 for in 来枚举某些 key 值
    1890     // 传入 keys 数组为参数
    1891     // 因为 JavaScript 下函数参数按值传递
    1892     // 所以 keys 当做参数传入后会在 `collectNonEnumProps` 方法中改变值
    1893     if (hasEnumBug) collectNonEnumProps(obj, keys);
    1894 
    1895     return keys;
    1896   };
    1897 
    1898   // Retrieve all the property names of an object.
    1899   // 返回一个对象的 keys 数组
    1900   // 不仅仅是 own enumerable properties
    1901   // 还包括原型链上继承的属性
    1902   _.allKeys = function(obj) {
    1903     // 容错
    1904     // 不是对象,则返回空数组
    1905     if (!_.isObject(obj)) return [];
    1906 
    1907     var keys = [];
    1908     for (var key in obj) keys.push(key);
    1909 
    1910     // Ahem, IE < 9.
    1911     // IE < 9 下的 bug,同 _.keys 方法
    1912     if (hasEnumBug) collectNonEnumProps(obj, keys);
    1913 
    1914     return keys;
    1915   };
    1916 
    1917   // Retrieve the values of an object's properties.
    1918   // ===== //
    1919   // _.values({one: 1, two: 2, three: 3});
    1920   // => [1, 2, 3]
    1921   // ===== //
    1922   // 将一个对象的所有 values 值放入数组中
    1923   // 仅限 own properties 上的 values
    1924   // 不包括原型链上的
    1925   // 并返回该数组
    1926   _.values = function(obj) {
    1927     // 仅包括 own properties
    1928     var keys = _.keys(obj);
    1929     var length = keys.length;
    1930     var values = Array(length);
    1931     for (var i = 0; i < length; i++) {
    1932       values[i] = obj[keys[i]];
    1933     }
    1934     return values;
    1935   };
    1936 
    1937   // Returns the results of applying the iteratee to each element of the object
    1938   // In contrast to _.map it returns an object
    1939   // 跟 _.map 方法很像
    1940   // 但是是专门为对象服务的 map 方法
    1941   // 迭代函数改变对象的 values 值
    1942   // 返回对象副本
    1943   _.mapObject = function(obj, iteratee, context) {
    1944     // 迭代函数
    1945     // 对每个键值对进行迭代
    1946     iteratee = cb(iteratee, context);
    1947 
    1948     var keys =  _.keys(obj),
    1949         length = keys.length,
    1950         results = {}, // 对象副本,该方法返回的对象
    1951         currentKey;
    1952 
    1953     for (var index = 0; index < length; index++) {
    1954       currentKey = keys[index];
    1955       // key 值不变
    1956       // 对每个 value 值用迭代函数迭代
    1957       // 返回经过函数运算后的值
    1958       results[currentKey] = iteratee(obj[currentKey], currentKey, obj);
    1959     }
    1960     return results;
    1961   };
    1962 
    1963   // Convert an object into a list of `[key, value]` pairs.
    1964   // 将一个对象转换为元素为 [key, value] 形式的数组
    1965   // _.pairs({one: 1, two: 2, three: 3});
    1966   // => [["one", 1], ["two", 2], ["three", 3]]
    1967   _.pairs = function(obj) {
    1968     var keys = _.keys(obj);
    1969     var length = keys.length;
    1970     var pairs = Array(length);
    1971     for (var i = 0; i < length; i++) {
    1972       pairs[i] = [keys[i], obj[keys[i]]];
    1973     }
    1974     return pairs;
    1975   };
    1976 
    1977   // Invert the keys and values of an object. The values must be serializable.
    1978   // 将一个对象的 key-value 键值对颠倒
    1979   // 即原来的 key 为 value 值,原来的 value 值为 key 值
    1980   // 需要注意的是,value 值不能重复(不然后面的会覆盖前面的)
    1981   // 且新构造的对象符合对象构造规则
    1982   // 并且返回新构造的对象
    1983   _.invert = function(obj) {
    1984     // 返回的新的对象
    1985     var result = {};
    1986     var keys = _.keys(obj);
    1987     for (var i = 0, length = keys.length; i < length; i++) {
    1988       result[obj[keys[i]]] = keys[i];
    1989     }
    1990     return result;
    1991   };
    1992 
    1993   // Return a sorted list of the function names available on the object.
    1994   // Aliased as `methods`
    1995   // 传入一个对象
    1996   // 遍历该对象的键值对(包括 own properties 以及 原型链上的)
    1997   // 如果某个 value 的类型是方法(function),则将该 key 存入数组
    1998   // 将该数组排序后返回
    1999   _.functions = _.methods = function(obj) {
    2000     // 返回的数组
    2001     var names = [];
    2002 
    2003     // if IE < 9
    2004     // 且对象重写了 `nonEnumerableProps` 数组中的某些方法
    2005     // 那么这些方法名是不会被返回的
    2006     // 可见放弃了 IE < 9 可能对 `toString` 等方法的重写支持
    2007     for (var key in obj) {
    2008       // 如果某个 key 对应的 value 值类型是函数
    2009       // 则将这个 key 值存入数组
    2010       if (_.isFunction(obj[key])) names.push(key);
    2011     }
    2012 
    2013     // 返回排序后的数组
    2014     return names.sort();
    2015   };
    2016 
    2017   // Extend a given object with all the properties in passed-in object(s).
    2018   // extend_.extend(destination, *sources)
    2019   // Copy all of the properties in the source objects over to the destination object
    2020   // and return the destination object
    2021   // It's in-order, so the last source will override properties of the same name in previous arguments.
    2022   // 将几个对象上(第二个参数开始,根据参数而定)的所有键值对添加到 destination 对象(第一个参数)上
    2023   // 因为 key 值可能会相同,所以后面的(键值对)可能会覆盖前面的
    2024   // 参数个数 >= 1
    2025   _.extend = createAssigner(_.allKeys);
    2026 
    2027   // Assigns a given object with all the own properties in the passed-in object(s)
    2028   // (https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/assign)
    2029   // 跟 extend 方法类似,但是只把 own properties 拷贝给第一个参数对象
    2030   // 只继承 own properties 的键值对
    2031   // 参数个数 >= 1
    2032   _.extendOwn = _.assign = createAssigner(_.keys);
    2033 
    2034   // Returns the first key on an object that passes a predicate test
    2035   // 跟数组方法的 _.findIndex 类似
    2036   // 找到对象的键值对中第一个满足条件的键值对
    2037   // 并返回该键值对 key 值
    2038   _.findKey = function(obj, predicate, context) {
    2039     predicate = cb(predicate, context);
    2040     var keys = _.keys(obj), key;
    2041     // 遍历键值对
    2042     for (var i = 0, length = keys.length; i < length; i++) {
    2043       key = keys[i];
    2044       // 符合条件,直接返回 key 值
    2045       if (predicate(obj[key], key, obj)) return key;
    2046     }
    2047   };
    2048 
    2049   // Return a copy of the object only containing the whitelisted properties.
    2050   // 根据一定的需求(key 值,或者通过 predicate 函数返回真假)
    2051   // 返回拥有一定键值对的对象副本
    2052   // 第二个参数可以是一个 predicate 函数
    2053   // 也可以是 >= 0 个 key
    2054   // _.pick(object, *keys)
    2055   // Return a copy of the object
    2056   // filtered to only have values for the whitelisted keys (or array of valid keys)
    2057   // Alternatively accepts a predicate indicating which keys to pick.
    2058   /*
    2059   _.pick({name: 'moe', age: 50, userid: 'moe1'}, 'name', 'age');
    2060   => {name: 'moe', age: 50}
    2061   _.pick({name: 'moe', age: 50, userid: 'moe1'}, ['name', 'age']);
    2062   => {name: 'moe', age: 50}
    2063   _.pick({name: 'moe', age: 50, userid: 'moe1'}, function(value, key, object) {
    2064     return _.isNumber(value);
    2065   });
    2066   => {age: 50}
    2067   */
    2068   _.pick = function(object, oiteratee, context) {
    2069     // result 为返回的对象副本
    2070     var result = {}, obj = object, iteratee, keys;
    2071 
    2072     // 容错
    2073     if (obj == null) return result;
    2074 
    2075     // 如果第二个参数是函数
    2076     if (_.isFunction(oiteratee)) {
    2077       keys = _.allKeys(obj);
    2078       iteratee = optimizeCb(oiteratee, context);
    2079     } else {
    2080       // 如果第二个参数不是函数
    2081       // 则后面的 keys 可能是数组
    2082       // 也可能是连续的几个并列的参数
    2083       // 用 flatten 将它们展开
    2084       keys = flatten(arguments, false, false, 1);
    2085 
    2086       // 也转为 predicate 函数判断形式
    2087       // 将指定 key 转化为 predicate 函数
    2088       iteratee = function(value, key, obj) { return key in obj; };
    2089       obj = Object(obj);
    2090     }
    2091 
    2092     for (var i = 0, length = keys.length; i < length; i++) {
    2093       var key = keys[i];
    2094       var value = obj[key];
    2095       // 满足条件
    2096       if (iteratee(value, key, obj)) result[key] = value;
    2097     }
    2098     return result;
    2099   };
    2100 
    2101   // Return a copy of the object without the blacklisted properties.
    2102   // 跟 _.pick 方法相对
    2103   // 返回 _.pick 的补集
    2104   // 即返回没有指定 keys 值的对象副本
    2105   // 或者返回不能通过 predicate 函数的对象副本
    2106   _.omit = function(obj, iteratee, context) {
    2107     if (_.isFunction(iteratee)) {
    2108       // _.negate 方法对 iteratee 的结果取反
    2109       iteratee = _.negate(iteratee);
    2110     } else {
    2111       var keys = _.map(flatten(arguments, false, false, 1), String);
    2112       iteratee = function(value, key) {
    2113         return !_.contains(keys, key);
    2114       };
    2115     }
    2116     return _.pick(obj, iteratee, context);
    2117   };
    2118 
    2119   // _.defaults(object, *defaults)
    2120   // Fill in a given object with default properties.
    2121   // Fill in undefined properties in object
    2122   // with the first value present in the following list of defaults objects.
    2123   // 和 _.extend 非常类似
    2124   // 区别是如果 *defaults 中出现了和 object 中一样的键
    2125   // 则不覆盖 object 的键值对
    2126   // 如果 *defaults 多个参数对象中有相同 key 的对象
    2127   // 则取最早出现的 value 值
    2128   // 参数个数 >= 1
    2129   _.defaults = createAssigner(_.allKeys, true);
    2130 
    2131   // Creates an object that inherits from the given prototype object.
    2132   // If additional properties are provided then they will be added to the
    2133   // created object.
    2134   // 给定 prototype
    2135   // 以及一些 own properties
    2136   // 构造一个新的对象并返回
    2137   _.create = function(prototype, props) {
    2138     var result = baseCreate(prototype);
    2139 
    2140     // 将 props 的键值对覆盖 result 对象
    2141     if (props) _.extendOwn(result, props);
    2142     return result;
    2143   };
    2144 
    2145   // Create a (shallow-cloned) duplicate of an object.
    2146   // 对象的 `浅复制` 副本
    2147   // 注意点:所有嵌套的对象或者数组都会跟原对象用同一个引用
    2148   // 所以是为浅复制,而不是深度克隆
    2149   _.clone = function(obj) {
    2150     // 容错,如果不是对象或者数组类型,则可以直接返回
    2151     // 因为一些基础类型是直接按值传递的
    2152     // 思考,arguments 呢? Nodelists 呢? HTML Collections 呢?
    2153     if (!_.isObject(obj))
    2154       return obj;
    2155 
    2156     // 如果是数组,则用 obj.slice() 返回数组副本
    2157     // 如果是对象,则提取所有 obj 的键值对覆盖空对象,返回
    2158     return _.isArray(obj) ? obj.slice() : _.extend({}, obj);
    2159   };
    2160 
    2161   // Invokes interceptor with the obj, and then returns obj.
    2162   // The primary purpose of this method is to "tap into" a method chain, in
    2163   // order to perform operations on intermediate results within the chain.
    2164   // _.chain([1,2,3,200])
    2165   // .filter(function(num) { return num % 2 == 0; })
    2166   // .tap(alert)
    2167   // .map(function(num) { return num * num })
    2168   // .value();
    2169   // => // [2, 200] (alerted)
    2170   // => [4, 40000]
    2171   // 主要是用在链式调用中
    2172   // 对中间值立即进行处理
    2173   _.tap = function(obj, interceptor) {
    2174     interceptor(obj);
    2175     return obj;
    2176   };
    2177 
    2178   // Returns whether an object has a given set of `key:value` pairs.
    2179   // attrs 参数为一个对象
    2180   // 判断 object 对象中是否有 attrs 中的所有 key-value 键值对
    2181   // 返回布尔值
    2182   _.isMatch = function(object, attrs) {
    2183     // 提取 attrs 对象的所有 keys
    2184     var keys = _.keys(attrs), length = keys.length;
    2185 
    2186     // 如果 object 为空
    2187     // 根据 attrs 的键值对数量返回布尔值
    2188     if (object == null) return !length;
    2189 
    2190     // 这一步有必要?
    2191     var obj = Object(object);
    2192 
    2193     // 遍历 attrs 对象键值对
    2194     for (var i = 0; i < length; i++) {
    2195       var key = keys[i];
    2196 
    2197       // 如果 obj 对象没有 attrs 对象的某个 key
    2198       // 或者对于某个 key,它们的 value 值不同
    2199       // 则证明 object 并不拥有 attrs 的所有键值对
    2200       // 则返回 false
    2201       if (attrs[key] !== obj[key] || !(key in obj)) return false;
    2202     }
    2203 
    2204     return true;
    2205   };
    2206 
    2207 
    2208   // Internal recursive comparison function for `isEqual`.
    2209   // "内部的"/ "递归地"/ "比较"
    2210   // 该内部方法会被递归调用
    2211   var eq = function(a, b, aStack, bStack) {
    2212     // Identical objects are equal. `0 === -0`, but they aren't identical.
    2213     // See the [Harmony `egal` proposal](http://wiki.ecmascript.org/doku.php?id=harmony:egal).
    2214     // a === b 时
    2215     // 需要注意 `0 === -0` 这个 special case
    2216     // 0 和 -0 被认为不相同(unequal)
    2217     // 至于原因可以参考上面的链接
    2218     if (a === b) return a !== 0 || 1 / a === 1 / b;
    2219 
    2220     // A strict comparison is necessary because `null == undefined`.
    2221     // 如果 a 和 b 有一个为 null(或者 undefined)
    2222     // 判断 a === b
    2223     if (a == null || b == null) return a === b;
    2224 
    2225     // Unwrap any wrapped objects.
    2226     // 如果 a 和 b 是 underscore OOP 的对象
    2227     // 那么比较 _wrapped 属性值(Unwrap)
    2228     if (a instanceof _) a = a._wrapped;
    2229     if (b instanceof _) b = b._wrapped;
    2230 
    2231     // Compare `[[Class]]` names.
    2232     // 用 Object.prototype.toString.call 方法获取 a 变量类型
    2233     var className = toString.call(a);
    2234 
    2235     // 如果 a 和 b 类型不相同,则返回 false
    2236     // 类型都不同了还比较个蛋!
    2237     if (className !== toString.call(b)) return false;
    2238 
    2239     switch (className) {
    2240       // Strings, numbers, regular expressions, dates, and booleans are compared by value.
    2241       // 以上五种类型的元素可以直接根据其 value 值来比较是否相等
    2242       case '[object RegExp]':
    2243       // RegExps are coerced to strings for comparison (Note: '' + /a/i === '/a/i')
    2244       case '[object String]':
    2245         // Primitives and their corresponding object wrappers are equivalent; thus, `"5"` is
    2246         // equivalent to `new String("5")`.
    2247         // 转为 String 类型进行比较
    2248         return '' + a === '' + b;
    2249 
    2250       // RegExp 和 String 可以看做一类
    2251       // 如果 obj 为 RegExp 或者 String 类型
    2252       // 那么 '' + obj 会将 obj 强制转为 String
    2253       // 根据 '' + a === '' + b 即可判断 a 和 b 是否相等
    2254       // ================
    2255 
    2256       case '[object Number]':
    2257         // `NaN`s are equivalent, but non-reflexive.
    2258         // Object(NaN) is equivalent to NaN
    2259         // 如果 +a !== +a
    2260         // 那么 a 就是 NaN
    2261         // 判断 b 是否也是 NaN 即可
    2262         if (+a !== +a) return +b !== +b;
    2263 
    2264         // An `egal` comparison is performed for other numeric values.
    2265         // 排除了 NaN 干扰
    2266         // 还要考虑 0 的干扰
    2267         // 用 +a 将 Number() 形式转为基本类型
    2268         // 即 +Number(1) ==> 1
    2269         // 0 需要特判
    2270         // 如果 a 为 0,判断 1 / +a === 1 / b
    2271         // 否则判断 +a === +b
    2272         return +a === 0 ? 1 / +a === 1 / b : +a === +b;
    2273 
    2274       // 如果 a 为 Number 类型
    2275       // 要注意 NaN 这个 special number
    2276       // NaN 和 NaN 被认为 equal
    2277       // ================
    2278 
    2279       case '[object Date]':
    2280       case '[object Boolean]':
    2281         // Coerce dates and booleans to numeric primitive values. Dates are compared by their
    2282         // millisecond representations. Note that invalid dates with millisecond representations
    2283         // of `NaN` are not equivalent.
    2284         return +a === +b;
    2285 
    2286       // Date 和 Boolean 可以看做一类
    2287       // 如果 obj 为 Date 或者 Boolean
    2288       // 那么 +obj 会将 obj 转为 Number 类型
    2289       // 然后比较即可
    2290       // +new Date() 是当前时间距离 1970 年 1 月 1 日 0 点的毫秒数
    2291       // +true => 1
    2292       // +new Boolean(false) => 0
    2293     }
    2294 
    2295 
    2296     // 判断 a 是否是数组
    2297     var areArrays = className === '[object Array]';
    2298 
    2299     // 如果 a 不是数组类型
    2300     if (!areArrays) {
    2301       // 如果 a 不是 object 或者 b 不是 object
    2302       // 则返回 false
    2303       if (typeof a != 'object' || typeof b != 'object') return false;
    2304 
    2305       // 通过上个步骤的 if 过滤
    2306       // !!保证到此的 a 和 b 均为对象!!
    2307 
    2308       // Objects with different constructors are not equivalent, but `Object`s or `Array`s
    2309       // from different frames are.
    2310       // 通过构造函数来判断 a 和 b 是否相同
    2311       // 但是,如果 a 和 b 的构造函数不同
    2312       // 也并不一定 a 和 b 就是 unequal
    2313       // 比如 a 和 b 在不同的 iframes 中!
    2314       // aCtor instanceof aCtor 这步有点不大理解,啥用?
    2315       var aCtor = a.constructor, bCtor = b.constructor;
    2316       if (aCtor !== bCtor && !(_.isFunction(aCtor) && aCtor instanceof aCtor &&
    2317                                _.isFunction(bCtor) && bCtor instanceof bCtor)
    2318                           && ('constructor' in a && 'constructor' in b)) {
    2319         return false;
    2320       }
    2321     }
    2322 
    2323     // Assume equality for cyclic structures. The algorithm for detecting cyclic
    2324     // structures is adapted from ES 5.1 section 15.12.3, abstract operation `JO`.
    2325 
    2326     // Initializing stack of traversed objects.
    2327     // It's done here since we only need them for objects and arrays comparison.
    2328     // 第一次调用 eq() 函数,没有传入 aStack 和 bStack 参数
    2329     // 之后递归调用都会传入这两个参数
    2330     aStack = aStack || [];
    2331     bStack = bStack || [];
    2332 
    2333     var length = aStack.length;
    2334 
    2335     while (length--) {
    2336       // Linear search. Performance is inversely proportional to the number of
    2337       // unique nested structures.
    2338       if (aStack[length] === a) return bStack[length] === b;
    2339     }
    2340 
    2341     // Add the first object to the stack of traversed objects.
    2342     aStack.push(a);
    2343     bStack.push(b);
    2344 
    2345     // Recursively compare objects and arrays.
    2346     // 将嵌套的对象和数组展开
    2347     // 如果 a 是数组
    2348     // 因为嵌套,所以需要展开深度比较
    2349     if (areArrays) {
    2350       // Compare array lengths to determine if a deep comparison is necessary.
    2351       // 根据 length 判断是否应该继续递归对比
    2352       length = a.length;
    2353 
    2354       // 如果 a 和 b length 属性大小不同
    2355       // 那么显然 a 和 b 不同
    2356       // return false 不用继续比较了
    2357       if (length !== b.length) return false;
    2358 
    2359       // Deep compare the contents, ignoring non-numeric properties.
    2360       while (length--) {
    2361         // 递归
    2362         if (!eq(a[length], b[length], aStack, bStack)) return false;
    2363       }
    2364     } else {
    2365       // 如果 a 不是数组
    2366       // 进入这个判断分支
    2367 
    2368       // Deep compare objects.
    2369       // 两个对象的深度比较
    2370       var keys = _.keys(a), key;
    2371       length = keys.length;
    2372 
    2373       // Ensure that both objects contain the same number of properties before comparing deep equality.
    2374       // a 和 b 对象的键数量不同
    2375       // 那还比较毛?
    2376       if (_.keys(b).length !== length) return false;
    2377 
    2378       while (length--) {
    2379         // Deep compare each member
    2380         // 递归比较
    2381         key = keys[length];
    2382         if (!(_.has(b, key) && eq(a[key], b[key], aStack, bStack))) return false;
    2383       }
    2384     }
    2385 
    2386     // Remove the first object from the stack of traversed objects.
    2387     // 与 aStack.push(a) 对应
    2388     // 此时 aStack 栈顶元素正是 a
    2389     // 而代码走到此步
    2390     // a 和 b isEqual 确认
    2391     // 所以 a,b 两个元素可以出栈
    2392     aStack.pop();
    2393     bStack.pop();
    2394 
    2395     // 深度搜索递归比较完毕
    2396     // 放心地 return true
    2397     return true;
    2398   };
    2399 
    2400   // Perform a deep comparison to check if two objects are equal.
    2401   // 判断两个对象是否一样
    2402   // new Boolean(true),true 被认为 equal
    2403   // [1, 2, 3], [1, 2, 3] 被认为 equal
    2404   // 0 和 -0 被认为 unequal
    2405   // NaN 和 NaN 被认为 equal
    2406   _.isEqual = function(a, b) {
    2407     return eq(a, b);
    2408   };
    2409 
    2410   // Is a given array, string, or object empty?
    2411   // An "empty" object has no enumerable own-properties.
    2412   // 是否是 {}、[] 或者 "" 或者 null、undefined
    2413   _.isEmpty = function(obj) {
    2414     if (obj == null) return true;
    2415 
    2416     // 如果是数组、类数组、或者字符串
    2417     // 根据 length 属性判断是否为空
    2418     // 后面的条件是为了过滤 isArrayLike 对于 {length: 10} 这样对象的判断 bug?
    2419     if (isArrayLike(obj) && (_.isArray(obj) || _.isString(obj) || _.isArguments(obj))) return obj.length === 0;
    2420 
    2421     // 如果是对象
    2422     // 根据 keys 数量判断是否为 Empty
    2423     return _.keys(obj).length === 0;
    2424   };
    2425 
    2426 
    2427   // Is a given value a DOM element?
    2428   // 判断是否为 DOM 元素
    2429   _.isElement = function(obj) {
    2430     // 确保 obj 不是 null, undefined 等假值
    2431     // 并且 obj.nodeType === 1
    2432     return !!(obj && obj.nodeType === 1);
    2433   };
    2434 
    2435   // Is a given value an array?
    2436   // Delegates to ECMA5's native Array.isArray
    2437   // 判断是否为数组
    2438   _.isArray = nativeIsArray || function(obj) {
    2439     return toString.call(obj) === '[object Array]';
    2440   };
    2441 
    2442   // Is a given variable an object?
    2443   // 判断是否为对象
    2444   // 这里的对象包括 function 和 object
    2445   _.isObject = function(obj) {
    2446     var type = typeof obj;
    2447     return type === 'function' || type === 'object' && !!obj;
    2448   };
    2449 
    2450   // Add some isType methods: isArguments, isFunction, isString, isNumber, isDate, isRegExp, isError.
    2451   // 其他类型判断
    2452   _.each(['Arguments', 'Function', 'String', 'Number', 'Date', 'RegExp', 'Error'], function(name) {
    2453     _['is' + name] = function(obj) {
    2454       return toString.call(obj) === '[object ' + name + ']';
    2455     };
    2456   });
    2457 
    2458   // Define a fallback version of the method in browsers (ahem, IE < 9), where
    2459   // there isn't any inspectable "Arguments" type.
    2460   // _.isArguments 方法在 IE < 9 下的兼容
    2461   // IE < 9 下对 arguments 调用 Object.prototype.toString.call 方法
    2462   // 结果是 => [object Object]
    2463   // 而并非我们期望的 [object Arguments]。
    2464   // so 用是否含有 callee 属性来做兼容
    2465   if (!_.isArguments(arguments)) {
    2466     _.isArguments = function(obj) {
    2467       return _.has(obj, 'callee');
    2468     };
    2469   }
    2470 
    2471   // Optimize `isFunction` if appropriate. Work around some typeof bugs in old v8,
    2472   // IE 11 (#1621), and in Safari 8 (#1929).
    2473   // _.isFunction 在 old v8, IE 11 和 Safari 8 下的兼容
    2474   // 觉得这里有点问题
    2475   // 我用的 chrome 49 (显然不是 old v8)
    2476   // 却也进入了这个 if 判断内部
    2477   if (typeof /./ != 'function' && typeof Int8Array != 'object') {
    2478     _.isFunction = function(obj) {
    2479       return typeof obj == 'function' || false;
    2480     };
    2481   }
    2482 
    2483   // Is a given object a finite number?
    2484   // 判断是否是有限的数字
    2485   _.isFinite = function(obj) {
    2486     return isFinite(obj) && !isNaN(parseFloat(obj));
    2487   };
    2488 
    2489   // Is the given value `NaN`? (NaN is the only number which does not equal itself).
    2490   // 判断是否是 NaN
    2491   // NaN 是唯一的一个 `自己不等于自己` 的 number 类型
    2492   // 这样写有 BUG
    2493   // _.isNaN(new Number(0)) => true
    2494   // 详见 https://github.com/hanzichi/underscore-analysis/issues/13
    2495   // 最新版本(edge 版)已经修复该 BUG
    2496   _.isNaN = function(obj) {
    2497     return _.isNumber(obj) && obj !== +obj;
    2498   };
    2499 
    2500   // Is a given value a boolean?
    2501   // 判断是否是布尔值
    2502   // 基础类型(true、 false)
    2503   // 以及 new Boolean() 两个方向判断
    2504   // 有点多余了吧?
    2505   // 个人觉得直接用 toString.call(obj) 来判断就可以了
    2506   _.isBoolean = function(obj) {
    2507     return obj === true || obj === false || toString.call(obj) === '[object Boolean]';
    2508   };
    2509 
    2510   // Is a given value equal to null?
    2511   // 判断是否是 null
    2512   _.isNull = function(obj) {
    2513     return obj === null;
    2514   };
    2515 
    2516   // Is a given variable undefined?
    2517   // 判断是否是 undefined
    2518   // undefined 能被改写 (IE < 9)
    2519   // undefined 只是全局对象的一个属性
    2520   // 在局部环境能被重新定义
    2521   // 但是「void 0」始终是 undefined
    2522   _.isUndefined = function(obj) {
    2523     return obj === void 0;
    2524   };
    2525 
    2526   // Shortcut function for checking if an object has a given property directly
    2527   // on itself (in other words, not on a prototype).
    2528   // 判断对象中是否有指定 key
    2529   // own properties, not on a prototype
    2530   _.has = function(obj, key) {
    2531     // obj 不能为 null 或者 undefined
    2532     return obj != null && hasOwnProperty.call(obj, key);
    2533   };
    2534 
    2535 
    2536   // Utility Functions
    2537   // 工具类方法
    2538   // 共 14 个扩展方法
    2539   // -----------------
    2540 
    2541   // Run Underscore.js in *noConflict* mode, returning the `_` variable to its
    2542   // previous owner. Returns a reference to the Underscore object.
    2543   // 如果全局环境中已经使用了 `_` 变量
    2544   // 可以用该方法返回其他变量
    2545   // 继续使用 underscore 中的方法
    2546   // var underscore = _.noConflict();
    2547   // underscore.each(..);
    2548   _.noConflict = function() {
    2549     root._ = previousUnderscore;
    2550     return this;
    2551   };
    2552 
    2553   // Keep the identity function around for default iteratees.
    2554   // 返回传入的参数,看起来好像没什么卵用
    2555   // 其实 _.identity 在 undescore 内大量作为迭代函数出现
    2556   // 能简化很多迭代函数的书写
    2557   _.identity = function(value) {
    2558     return value;
    2559   };
    2560 
    2561   // Predicate-generating functions. Often useful outside of Underscore.
    2562   _.constant = function(value) {
    2563     return function() {
    2564       return value;
    2565     };
    2566   };
    2567 
    2568   _.noop = function(){};
    2569 
    2570   // 传送门
    2571   /*
    2572   var property = function(key) {
    2573     return function(obj) {
    2574       return obj == null ? void 0 : obj[key];
    2575     };
    2576   };
    2577   */
    2578   _.property = property;
    2579 
    2580   // Generates a function for a given object that returns a given property.
    2581   _.propertyOf = function(obj) {
    2582     return obj == null ? function(){} : function(key) {
    2583       return obj[key];
    2584     };
    2585   };
    2586 
    2587   // Returns a predicate for checking whether an object has a given set of
    2588   // `key:value` pairs.
    2589   // 判断一个给定的对象是否有某些键值对
    2590   _.matcher = _.matches = function(attrs) {
    2591     attrs = _.extendOwn({}, attrs);
    2592     return function(obj) {
    2593       return _.isMatch(obj, attrs);
    2594     };
    2595   };
    2596 
    2597   // Run a function **n** times.
    2598   // 执行某函数 n 次
    2599   _.times = function(n, iteratee, context) {
    2600     var accum = Array(Math.max(0, n));
    2601     iteratee = optimizeCb(iteratee, context, 1);
    2602     for (var i = 0; i < n; i++)
    2603       accum[i] = iteratee(i);
    2604     return accum;
    2605   };
    2606 
    2607   // Return a random integer between min and max (inclusive).
    2608   // 返回一个 [min, max] 范围内的任意整数
    2609   _.random = function(min, max) {
    2610     if (max == null) {
    2611       max = min;
    2612       min = 0;
    2613     }
    2614     return min + Math.floor(Math.random() * (max - min + 1));
    2615   };
    2616 
    2617   // A (possibly faster) way to get the current timestamp as an integer.
    2618   // 返回当前时间的 "时间戳"(单位 ms)
    2619   // 其实并不是时间戳,时间戳还要除以 1000(单位 s)
    2620   // +new Date 类似
    2621   _.now = Date.now || function() {
    2622     return new Date().getTime();
    2623   };
    2624 
    2625   // List of HTML entities for escaping.
    2626   // HTML 实体编码
    2627   // escapeMap 用于编码
    2628   // see @http://www.cnblogs.com/zichi/p/5135636.html
    2629   // in PHP, htmlspecialchars — Convert special characters to HTML entities
    2630   // see @http://php.net/manual/zh/function.htmlspecialchars.php
    2631   // 能将 & " ' < > 转为实体编码(下面的前 5 种)
    2632   var escapeMap = {
    2633     '&': '&amp;',
    2634     '<': '&lt;',
    2635     '>': '&gt;',
    2636     '"': '&quot;',
    2637     // 以上四个为最常用的字符实体
    2638     // 也是仅有的可以在所有环境下使用的实体字符(其他应该用「实体数字」,如下)
    2639     // 浏览器也许并不支持所有实体名称(对实体数字的支持却很好)
    2640     "'": '&#x27;',
    2641     '`': '&#x60;'
    2642   };
    2643 
    2644   // _.invert 方法将一个对象的键值对对调
    2645   // unescapeMap 用于解码
    2646   var unescapeMap = _.invert(escapeMap);
    2647 
    2648   // Functions for escaping and unescaping strings to/from HTML interpolation.
    2649   var createEscaper = function(map) {
    2650     var escaper = function(match) {
    2651       return map[match];
    2652     };
    2653 
    2654     // Regexes for identifying a key that needs to be escaped
    2655     // 正则替换
    2656     // 注意下 ?:
    2657     var source = '(?:' + _.keys(map).join('|') + ')';
    2658 
    2659     // 正则 pattern
    2660     var testRegexp = RegExp(source);
    2661 
    2662     // 全局替换
    2663     var replaceRegexp = RegExp(source, 'g');
    2664     return function(string) {
    2665       string = string == null ? '' : '' + string;
    2666       return testRegexp.test(string) ? string.replace(replaceRegexp, escaper) : string;
    2667     };
    2668   };
    2669 
    2670   // Escapes a string for insertion into HTML, replacing &, <, >, ", `, and ' characters.
    2671   // 编码,防止被 XSS 攻击等一些安全隐患
    2672   _.escape = createEscaper(escapeMap);
    2673 
    2674   // The opposite of escape
    2675   // replaces &amp;, &lt;, &gt;, &quot;, &#96; and &#x27; with their unescaped counterparts
    2676   // 解码
    2677   _.unescape = createEscaper(unescapeMap);
    2678 
    2679   // If the value of the named `property` is a function then invoke it with the
    2680   // `object` as context; otherwise, return it.
    2681   _.result = function(object, property, fallback) {
    2682     var value = object == null ? void 0 : object[property];
    2683     if (value === void 0) {
    2684       value = fallback;
    2685     }
    2686     return _.isFunction(value) ? value.call(object) : value;
    2687   };
    2688 
    2689   // Generate a unique integer id (unique within the entire client session).
    2690   // Useful for temporary DOM ids.
    2691   // 生成客户端临时的 DOM ids
    2692   var idCounter = 0;
    2693   _.uniqueId = function(prefix) {
    2694     var id = ++idCounter + '';
    2695     return prefix ? prefix + id : id;
    2696   };
    2697 
    2698   // By default, Underscore uses ERB-style template delimiters, change the
    2699   // following template settings to use alternative delimiters.
    2700   // ERB => Embedded Ruby
    2701   // Underscore 默认采用 ERB-style 风格模板,也可以根据自己习惯自定义模板
    2702   // 1. <%  %> - to execute some code
    2703   // 2. <%= %> - to print some value in template
    2704   // 3. <%- %> - to print some values HTML escaped
    2705   _.templateSettings = {
    2706     // 三种渲染模板
    2707     evaluate    : /<%([sS]+?)%>/g,
    2708     interpolate : /<%=([sS]+?)%>/g,
    2709     escape      : /<%-([sS]+?)%>/g
    2710   };
    2711 
    2712   // When customizing `templateSettings`, if you don't want to define an
    2713   // interpolation, evaluation or escaping regex, we need one that is
    2714   // guaranteed not to match.
    2715   var noMatch = /(.)^/;
    2716 
    2717   // Certain characters need to be escaped so that they can be put into a
    2718   // string literal.
    2719   var escapes = {
    2720     "'":      "'",
    2721     '\':     '\',
    2722     '
    ':     'r',  // 回车符
    2723     '
    ':     'n',  // 换行符
    2724     // http://stackoverflow.com/questions/16686687/json-stringify-and-u2028-u2029-check
    2725     'u2028': 'u2028', // Line separator
    2726     'u2029': 'u2029'  // Paragraph separator
    2727   };
    2728 
    2729   // RegExp pattern
    2730   var escaper = /\|'|
    |
    |u2028|u2029/g;
    2731 
    2732   var escapeChar = function(match) {
    2733     /**
    2734       '      => \'
    2735       \     => \\
    2736       
         => \r
    2737       
         => \n
    2738       u2028 => \u2028
    2739       u2029 => \u2029
    2740     **/
    2741     return '\' + escapes[match];
    2742   };
    2743 
    2744   // 将 JavaScript 模板编译为可以用于页面呈现的函数
    2745   // JavaScript micro-templating, similar to John Resig's implementation.
    2746   // Underscore templating handles arbitrary delimiters, preserves whitespace,
    2747   // and correctly escapes quotes within interpolated code.
    2748   // NB: `oldSettings` only exists for backwards compatibility.
    2749   // oldSettings 参数为了兼容 underscore 旧版本
    2750   // setting 参数可以用来自定义字符串模板(但是 key 要和 _.templateSettings 中的相同,才能 overridden)
    2751   // 1. <%  %> - to execute some code
    2752   // 2. <%= %> - to print some value in template
    2753   // 3. <%- %> - to print some values HTML escaped
    2754   // Compiles JavaScript templates into functions
    2755   // _.template(templateString, [settings])
    2756   _.template = function(text, settings, oldSettings) {
    2757     // 兼容旧版本
    2758     if (!settings && oldSettings)
    2759       settings = oldSettings;
    2760 
    2761     // 相同的 key,优先选择 settings 对象中的
    2762     // 其次选择 _.templateSettings 对象中的
    2763     // 生成最终用来做模板渲染的字符串
    2764     // 自定义模板优先于默认模板 _.templateSettings
    2765     // 如果定义了相同的 key,则前者会覆盖后者
    2766     settings = _.defaults({}, settings, _.templateSettings);
    2767 
    2768     // Combine delimiters into one regular expression via alternation.
    2769     // 正则表达式 pattern,用于正则匹配 text 字符串中的模板字符串
    2770     // /<%-([sS]+?)%>|<%=([sS]+?)%>|<%([sS]+?)%>|$/g
    2771     // 注意最后还有个 |$
    2772     var matcher = RegExp([
    2773       // 注意下 pattern 的 source 属性
    2774       (settings.escape || noMatch).source,
    2775       (settings.interpolate || noMatch).source,
    2776       (settings.evaluate || noMatch).source
    2777     ].join('|') + '|$', 'g');
    2778 
    2779     // Compile the template source, escaping string literals appropriately.
    2780     // 编译模板字符串,将原始的模板字符串替换成函数字符串
    2781     // 用拼接成的函数字符串生成函数(new Function(...))
    2782     var index = 0;
    2783 
    2784     // source 变量拼接的字符串用来生成函数
    2785     // 用于当做 new Function 生成函数时的函数字符串变量
    2786     // 记录编译成的函数字符串,可通过 _.template(tpl).source 获取(_.template(tpl) 返回方法)
    2787     var source = "__p+='";
    2788 
    2789     // replace 函数不需要为返回值赋值,主要是为了在函数内对 source 变量赋值
    2790     // 将 text 变量中的模板提取出来
    2791     // match 为匹配的整个串
    2792     // escape/interpolate/evaluate 为匹配的子表达式(如果没有匹配成功则为 undefined)
    2793     // offset 为字符匹配(match)的起始位置(偏移量)
    2794     text.replace(matcher, function(match, escape, interpolate, evaluate, offset) {
    2795       // 
     => \n
    2796       source += text.slice(index, offset).replace(escaper, escapeChar);
    2797 
    2798       // 改变 index 值,为了下次的 slice
    2799       index = offset + match.length;
    2800 
    2801       if (escape) {
    2802         // 需要对变量进行编码(=> HTML 实体编码)
    2803         // 避免 XSS 攻击
    2804         source += "'+
    ((__t=(" + escape + "))==null?'':_.escape(__t))+
    '";
    2805       } else if (interpolate) {
    2806         // 单纯的插入变量
    2807         source += "'+
    ((__t=(" + interpolate + "))==null?'':__t)+
    '";
    2808       } else if (evaluate) {
    2809         // 可以直接执行的 JavaScript 语句
    2810         // 注意 "__p+=",__p 为渲染返回的字符串
    2811         source += "';
    " + evaluate + "
    __p+='";
    2812       }
    2813 
    2814       // Adobe VMs need the match returned to produce the correct offset.
    2815       // return 的作用是?
    2816       // 将匹配到的内容原样返回(Adobe VMs 需要返回 match 来使得 offset 值正常)
    2817       return match;
    2818     });
    2819 
    2820     source += "';
    ";
    2821 
    2822     // By default, `template` places the values from your data in the local scope via the `with` statement.
    2823     // However, you can specify a single variable name with the variable setting.
    2824     // This can significantly improve the speed at which a template is able to render.
    2825     // If a variable is not specified, place data values in local scope.
    2826     // 指定 scope
    2827     // 如果设置了 settings.variable,能显著提升模板的渲染速度
    2828     // 否则,默认用 with 语句指定作用域
    2829     if (!settings.variable)
    2830       source = 'with(obj||{}){
    ' + source + '}
    ';
    2831 
    2832     // 增加 print 功能
    2833     // __p 为返回的字符串
    2834     source = "var __t,__p='',__j=Array.prototype.join," +
    2835       "print=function(){__p+=__j.call(arguments,'');};
    " +
    2836       source + 'return __p;
    ';
    2837 
    2838     try {
    2839       // render 方法,前两个参数为 render 方法的参数
    2840       // obj 为传入的 JSON 对象,传入 _ 参数使得函数内部能用 Underscore 的函数
    2841       var render = new Function(settings.variable || 'obj', '_', source);
    2842     } catch (e) {
    2843       // 抛出错误
    2844       e.source = source;
    2845       throw e;
    2846     }
    2847 
    2848     // 返回的函数
    2849     // data 一般是 JSON 数据,用来渲染模板
    2850     var template = function(data) {
    2851       // render 为模板渲染函数
    2852       // 传入参数 _ ,使得模板里 <%  %> 里的代码能用 underscore 的方法
    2853       //(<%  %> - to execute some code)
    2854       return render.call(this, data, _);
    2855     };
    2856 
    2857     // Provide the compiled source as a convenience for precompilation.
    2858     // template.source for debug?
    2859     // obj 与 with(obj||{}) 中的 obj 对应
    2860     var argument = settings.variable || 'obj';
    2861 
    2862     // 可通过 _.template(tpl).source 获取
    2863     // 可以用来预编译,在服务端预编译好,直接在客户端生成代码,客户端直接调用方法
    2864     // 这样如果出错就能打印出错行
    2865     // Precompiling your templates can be a big help when debugging errors you can't reproduce.
    2866     // This is because precompiled templates can provide line numbers and a stack trace,
    2867     // something that is not possible when compiling templates on the client.
    2868     // The source property is available on the compiled template function for easy precompilation.
    2869     // see @http://stackoverflow.com/questions/18755292/underscore-js-precompiled-templates-using
    2870     // see @http://stackoverflow.com/questions/13536262/what-is-javascript-template-precompiling
    2871     // see @http://stackoverflow.com/questions/40126223/can-anyone-explain-underscores-precompilation-in-template
    2872     // JST is a server-side thing, not client-side.
    2873     // This mean that you compile Unserscore template on server side by some server-side script and save the result in a file.
    2874     // Then use this file as compiled Unserscore template.
    2875     template.source = 'function(' + argument + '){
    ' + source + '}';
    2876 
    2877     return template;
    2878   };
    2879 
    2880   // Add a "chain" function. Start chaining a wrapped Underscore object.
    2881   // 使支持链式调用
    2882   /**
    2883   // 非 OOP 调用 chain
    2884   _.chain([1, 2, 3])
    2885     .map(function(a) { return a * 2; })
    2886     .reverse().value(); // [6, 4, 2]
    2887   // OOP 调用 chain
    2888   _([1, 2, 3])
    2889     .chain()
    2890     .map(function(a){ return a * 2; })
    2891     .first()
    2892     .value(); // 2
    2893   **/
    2894   _.chain = function(obj) {
    2895     // 无论是否 OOP 调用,都会转为 OOP 形式
    2896     // 并且给新的构造对象添加了一个 _chain 属性
    2897     var instance = _(obj);
    2898 
    2899     // 标记是否使用链式操作
    2900     instance._chain = true;
    2901 
    2902     // 返回 OOP 对象
    2903     // 可以看到该 instance 对象除了多了个 _chain 属性
    2904     // 其他的和直接 _(obj) 的结果一样
    2905     return instance;
    2906   };
    2907 
    2908   // OOP
    2909   // ---------------
    2910   // If Underscore is called as a function, it returns a wrapped object that
    2911   // can be used OO-style. This wrapper holds altered versions of all the
    2912   // underscore functions. Wrapped objects may be chained.
    2913 
    2914   // OOP
    2915   // 如果 `_` 被当做方法(构造函数)调用, 则返回一个被包装过的对象
    2916   // 该对象能使用 underscore 的所有方法
    2917   // 并且支持链式调用
    2918 
    2919   // Helper function to continue chaining intermediate results.
    2920   // 一个帮助方法(Helper function)
    2921   var result = function(instance, obj) {
    2922     // 如果需要链式操作,则对 obj 运行 _.chain 方法,使得可以继续后续的链式操作
    2923     // 如果不需要,直接返回 obj
    2924     return instance._chain ? _(obj).chain() : obj;
    2925   };
    2926 
    2927   // Add your own custom functions to the Underscore object.
    2928   // 可向 underscore 函数库扩展自己的方法
    2929   // obj 参数必须是一个对象(JavaScript 中一切皆对象)
    2930   // 且自己的方法定义在 obj 的属性上
    2931   // 如 obj.myFunc = function() {...}
    2932   // 形如 {myFunc: function(){}}
    2933   // 之后便可使用如下: _.myFunc(..) 或者 OOP _(..).myFunc(..)
    2934   _.mixin = function(obj) {
    2935     // 遍历 obj 的 key,将方法挂载到 Underscore 上
    2936     // 其实是将方法浅拷贝到 _.prototype 上
    2937     _.each(_.functions(obj), function(name) {
    2938       // 直接把方法挂载到 _[name] 上
    2939       // 调用类似 _.myFunc([1, 2, 3], ..)
    2940       var func = _[name] = obj[name];
    2941 
    2942       // 浅拷贝
    2943       // 将 name 方法挂载到 _ 对象的原型链上,使之能 OOP 调用
    2944       _.prototype[name] = function() {
    2945         // 第一个参数
    2946         var args = [this._wrapped];
    2947 
    2948         // arguments 为 name 方法需要的其他参数
    2949         push.apply(args, arguments);
    2950         // 执行 func 方法
    2951         // 支持链式操作
    2952         return result(this, func.apply(_, args));
    2953       };
    2954     });
    2955   };
    2956 
    2957   // Add all of the Underscore functions to the wrapper object.
    2958   // 将前面定义的 underscore 方法添加给包装过的对象
    2959   // 即添加到 _.prototype 中
    2960   // 使 underscore 支持面向对象形式的调用
    2961   _.mixin(_);
    2962 
    2963   // Add all mutator Array functions to the wrapper.
    2964   // 将 Array 原型链上有的方法都添加到 underscore 中
    2965   _.each(['pop', 'push', 'reverse', 'shift', 'sort', 'splice', 'unshift'], function(name) {
    2966     var method = ArrayProto[name];
    2967     _.prototype[name] = function() {
    2968       var obj = this._wrapped;
    2969       method.apply(obj, arguments);
    2970 
    2971       if ((name === 'shift' || name === 'splice') && obj.length === 0)
    2972         delete obj[0];
    2973 
    2974       // 支持链式操作
    2975       return result(this, obj);
    2976     };
    2977   });
    2978 
    2979   // Add all accessor Array functions to the wrapper.
    2980   // 添加 concat、join、slice 等数组原生方法给 Underscore
    2981   _.each(['concat', 'join', 'slice'], function(name) {
    2982     var method = ArrayProto[name];
    2983     _.prototype[name] = function() {
    2984       return result(this, method.apply(this._wrapped, arguments));
    2985     };
    2986   });
    2987 
    2988   // Extracts the result from a wrapped and chained object.
    2989   // 一个包装过(OOP)并且链式调用的对象
    2990   // 用 value 方法获取结果
    2991   // _(obj).value === obj?
    2992   _.prototype.value = function() {
    2993     return this._wrapped;
    2994   };
    2995 
    2996   // Provide unwrapping proxy for some methods used in engine operations
    2997   // such as arithmetic and JSON stringification.
    2998   _.prototype.valueOf = _.prototype.toJSON = _.prototype.value;
    2999 
    3000   _.prototype.toString = function() {
    3001     return '' + this._wrapped;
    3002   };
    3003 
    3004   // AMD registration happens at the end for compatibility with AMD loaders
    3005   // that may not enforce next-turn semantics on modules. Even though general
    3006   // practice for AMD registration is to be anonymous, underscore registers
    3007   // as a named module because, like jQuery, it is a base library that is
    3008   // popular enough to be bundled in a third party lib, but not be part of
    3009   // an AMD load request. Those cases could generate an error when an
    3010   // anonymous define() is called outside of a loader request.
    3011   // 兼容 AMD 规范
    3012   if (typeof define === 'function' && define.amd) {
    3013     define('underscore', [], function() {
    3014       return _;
    3015     });
    3016   }
    3017 }.call(this));
  • 相关阅读:
    Server Application Unavailable 解决办法 (转)
    SQL SERVER:分割函数 split
    Win32汇编_基础
    Win32汇编_异常_筛选器
    创建进程常用函数
    内存常用函数
    桃花庵歌
    文天祥的诗
    Socket I/O模型全接触
    函数指针的神奇
  • 原文地址:https://www.cnblogs.com/jasonoiu/p/underscore-analysis.html
Copyright © 2020-2023  润新知