Underscore.js: Annotated Source Code | Hacker News Reader

Underscore.js: Annotated Source Code

documentcloud.github.com

65 pointsshawndumas25 comments

I wish more open source libraries had this. This seems to be a trend in the javascript ecosystems. Coffeescript also has this. http://jashkenas.github.com/coffee-script/

Same author; the venerable Jeremy Ashkenas[1].

And yes; quality is fractal.

----

[1]: http://github.com/jashkenas

Next to jQuery, Underscore is my most-used JS library. Makes scripting client-side behavior so much more pleasant.

"It's the tie to go along with jQuery's tux."[1]

-----

[1]: http://documentcloud.github.com/underscore/

I don't understand this statement. Initially when I saw underscore.js a few weeks ago, I was under the impression it was a light weight js library for when you didn't want to use jquery or something even heavier. Do you use this in conjunction with jquery? Could someone please explain the use case for this library as their is a fair bit of duplication between this and jquery.

Underscore is intended to fit in nicely alongside jQuery -- in the handful of places where the two overlap (map, each, bind), Underscore delegates to the native browser implementations, providing quite a substantial performance boost over the jQuery versions. There is a benchmark script at the bottom of this page, and you can run it in your browser to see the difference:

http://documentcloud.github.com/underscore/test/test.html

In general, Underscore is intended for logic and data manipulation, and jQuery handles the DOM and Ajax calls.

Thank you for clarifying, I appreciate it. There are some very nice data manipulation functions in underscore, and its speed is impressive. I will definitely look into it more.

Totally agreed. Underscore has quickly become the one js library that I cannot live without, no matter what.

I tweeted this yesterday:

Why does Underscore.js get the order of arguments wrong? There’s a reason why it’s map(fn, l), not map(l, fn). And the reason is currying.

I find that very annoying for the kind of functional programming I tend to do. For that reason alone I started looking at Wu.js instead.

Am I missing something?

Order of arguments shouldn't be a fundamental problem for currying -- libraries like Functional.js allow you to curry from the left, or to curry from the right, as you desire.

However, having higher-order functions in JavaScript take their function argument in the final position is an extremely common and important pattern in JavaScript. Most libraries prefer this:

    call(arg, arg, function() {
      ...
    });

Instead of this (which hides relevant arguments far away from the actual call site):

    call(function() {
      ...
    }, arg, arg);

That's a good point. However, I find it funny that you should mention another functional library as a way around the issue. Doesn't that defeat the purpose of Underscore?

I have a feeling that either the authors of Underscore don't fully get functional programming, or I don't. Of course, the latter is much more likely, that's why I'm looking for someone to set me straight.

Full disclosure: I'm the author.

Depending on your definition, nothing in JavaScript is "fully functional programming", because then it would have to be side-effect-free, and JavaScript is very much not that language.

Calling them "functional helpers" is mostly a way of distinguishing the style in which you use them, as opposed to the object-oriented versions of the same helper functions, which can be found in libraries like Prototype.js. The idea here being that you can use them in a functional style without having to extend native objects.

As I mentioned above, calling "map" with the iterator as the final argument isn't a limitation here -- it's a feature. There aren't many (any) situations I've ever seen in real-world JS where you'd want to curry together a list of iterators, and then map them together across the array, all at once. And if you do want to do such a thing, you can accomplish it either like this:

    _.map(list, function(item) {
      return convert1(convert2(convert3(item)));
    });

Or, if you want to get fancy, take a look at "compose":

http://documentcloud.github.com/underscore/#compose

    _.map(list, _.compose(convert1, convert2, convert3));

You really want the order of arguments to be 'fn,list' when you're working with a language that has partial function application (currying with no special syntax, basically). In a language like Javascript where you have to resort to a curry function, there's no practical difference. A curry function implementation can actually be made to work with either argument order pretty easily.

And in javascript, having the function last is relatively standard and much nicer to look at.

I mainly use Object-Oriented Style[1].

-----

http://documentcloud.github.com/underscore/#styles

Can you do things like

    var sum = curry(reduce, add);

with the OO style?

Am I wrong in thinking that this kind of currying is one of the fundamental building blocks of functional programming?

Do you mean like this?

  var sum = function (a) {
      return _(a).reduce(function (m, n) {
          return m + n;
      }, 0);
  };

  sum([1,2,3,4,5,6,7,8,9]); // => 45

Or am I not getting you?

That's one way to do it, but you're falling back to explicitly defining a new function, rather than creating it by combining higher-order functions. Which kinda defeats the point.

All I would have to do is abstract the outer function out and call it curry (partial[1], really).

  var add = function (m, n) {
          return m + n;
      },
      partial = function (mth, fn) {
          return function (l) { return _(l)[mth](fn, 0); };
      },
      sum = partial('reduce', add);

  sum([1,2,3,4,5,6,7,8,9]); // => 45

-----

[1]: http://lambda-the-ultimate.org/node/2266

I'd love to know if there's a lib for generating annotations like this from source comments. I've always loved docs tha include the code for reference, helps to see what's actually going on :)

http://github.com/jashkenas/docco

http://github.com/rtomayko/rocco

http://github.com/rtomayko/shocco

Docco is CoffeeScript/JavaScript, Rocco is Ruby, Shocco is Shell, and there's one more (that I know of) ... Pycco for Python:

http://github.com/fitzgen/pycco

And a first cousin, once removed: Dox (JavaScript):

http://visionmedia.github.com/dox/

Dox seems to just be explicitly marked documentation, not every comment.

Pycco claims to support Python, Ruby, JavaScript, CoffeeScript, Scheme, and Lua.

I just submitted one earlier this morning[1].

-----

[1]: http://news.ycombinator.com/item?id=1767758

This is just a style comment, but given JavaScript's open class prototypes and expando objects, I generally prefer to write these methods as new members on their natural classes. For example, the RegEx escape method would be on the RegEx class itself, rather than being a stand alone function.

Other than that, this is an incredibly useful set of functions that any JavaScript developer should have in their toolkit.

You mean like putting the methods into the native classes' prototypes? That's a bad idea. The reason why it is a bad idea is that you cannot extend a prototype only within a scope, i.e if you change the prototype, it'll be changed regardless of whether it'll break another library, or that another library replaces your methods and thus render your library broken. This opens up the risk that you'll end up with bugs that are hard to trace to their source.

Reply on news.ycombinator.com