Like most front-end developers I don’t have a Computer Science degree and started to program using high level languages, it took me a while to stumble into Linked Lists, that’s why I’m going to explain the basic use cases, pros/cons of this simple data-structure and why it’s widely used. - You probably used it before without knowing.

This post was motived by this tweet:

Can anyone explain what a Linked List is and why I’d use one (if I even could in Ruby, PHP, JS). I’m not quite grokking their purpose?— integralist (@integralist) May 12, 2013

Linked Lists are not indexed

The main difference from an Array is that Linked Lists are not indexed.

The Linked List doesn’t hold a reference to all the items that it stores, it usually only contain references to its head (first element) and/or tail (last item). Each item of the Linked List is responsible for storing a reference to the next and/or previous element of the list.

Not having indexes is the main advantage and drawback of Linked Lists.

It doesn’t support arbitrary access

The search and iteration over a linked list is usually sequential.

On an Array you can grab the 4th item by it’s index, like myArray[3]. Since the Linked Lists doesn’t contain indexes (or references to all items) you need to grab a reference to the head or tail of the list and iterate over the list items like myLinkedList.head.next.next.next.

As you can see, Linked Lists are not recommended when you need arbitrary access to the elements, in this case Arrays or Dictionaries/Hashes (plain old JavaScript objects) are better suited.

Adding/removing items is usually faster

Adding and removing items from a non-indexed list is usually faster since it doesn’t need to rebuild the index every time the items change, it just needs to update the references to the next and/or previous element.

Searching/iteration can be slower/cubersome

The lack of index and the simple structure can be a drawback, since you can’t skip to a certain position on the list some operations will require iterating over most nodes on the list or all of the list elements. - There are always pros and cons.

Linked lists usually don’t contain helper methods like the ES5 Array methods (map, reduce, some, forEach) which can make things a little bit harder to manage (you can implement it by yourself tho).

Lower-Level languages

Liked Lists are very common in lower level languages since you usually need to define how many bytes should be allocated for each object beforehand (returning a pointer to that location in memory and making sure it doesn’t collide with other pointers). Since linked lists doesn’t store a reference to all the items they can expand indefinitely without causing memory overlaps and items don’t need to be stored sequentially in memory or have the same size – it’s a very flexible data structure and very common because of that.

Basic Implementation

The very-minimal implementation of a linked list in JavaScript is:

// items of the list
var bird = {name:'Mockingbird'};
var cat = {name:'Keyboard'};
var dog = {name:'Fort'};
var duck = {name:'Scrooge'};

// the linked-list itself
var animals = {
    head : bird
};
// each item of the list stores reference to the next one
bird.next = cat;
cat.next = dog;
dog.next = duck;

To iterate over all items in the list you can simply do:

var animal = animals.head;
while (animal) {
    console.log(animal.name);
    animal = animal.next;
}

The DOM is a Linked List

The DOM is a linked list, you use node.nextSibling, node.parentNode, node.firstChild, etc to iterate over the elements. Linked Lists are very good for this use case since we add/remove items and rearrange the nodes many times during the application life cycle. It also simplifies the traversal a lot, navigating lists by index can be very cumbersome, node.previousSibling is way simpler than nodesList[nodesList.indexOf(node) - 1].

Doubly/Multiply/Circular Linked List

Linked lists can have references to other elements besides the next element. It is specially useful when you need to iterate the list backwards or need to speed up some complex iteration/manipulation.

A Doubly Linked List is a list where the nodes also contains references to the previous elements.

// doubly-linked
cat.prev = bird;
dog.prev = cat;
// storing the tail (last item) is also useful in some cases
animals.tail = dog;

In a Multiply Linked List each node contains reference to 2 or more nodes. Circular lists have the tail.next point to the list head and are less common.

On rocambole I use a doubly-linked list for the tokens (prev and next references). On the nodes I use a multiply linked list (references to parent, startToken, endToken, next and prev), it simplifies the AST manipulation a lot and allows the creation of helper methods similar to jQuery very easily.

Cross references are extremely useful, don’t let the lack of index be a limitation, abuse it when needed.

Removing/Adding Items

Another big advantage of linked lists is that if you add/remove items during the iteration it usually doesn’t cause undesired side effects, imagine this scenario:

var animals = [bird, cat, dog, duck];
for(var i = 0, n = animals.length; i < n; i++) {
    // OOPS! TypeError!
    // length changed during iteration, animals[3] doesn't exist anymore.
    var animal = animals[i];
    console.log(animal.name);
    if (animal.name === 'Fort') {
        animals.splice(i, 1);
    }
}

If you used a Linked List (or didn't cached the animals.length value) this problem wouldn't exist, removing items from a linked list doesn't break the iteration:

var animal = animals.head;
while (animal) {
    console.log(animal.name);
    if (animal.name === 'Fort') {
        removeItem(animals, animal);
    }
    animal = animal.next;
}

// to remove an item we just need to remove all references to it
function removeItem(list, item){
    // assuming that list is doubly-linked
    if (list.head === item) list.head = item.next;
    if (list.tail === item) list.tail = item.prev;
    if (item.prev) item.prev.next = item.next;
    item.next = item.prev = null;
    // on a singly-linked list the process is more expensive since you need to
    // loop over the items to find out where to remove
}

Sum Up

I hope it was clear enough and that you find some good use for it. I find it really important to learn about data structures and other computer sciency subjects, you never know when this kind of knowledge can be useful and a lot of smart people already thought about these problems before, it's good to have options.

Wikipedia contains a detailed explanation of the pros/cons in case you are interested in getting all the details. (not for dummies tho).

You could also create a generic implementation that works for multiple cases but that is outside the scope of this article, I tried to keep it as simple as possible just to explain the concept and not a specific implementation - a quick Google search returned many results. I have an old implementation on my personal files but to be honest I'm not using it on any projects and nowadays I would build it in a different way - make it a doubly linked list, remove the iteration helpers and simplify the structure (there is no need for a wrapper object for each node, prev and next are very unlikely to cause name collisions). Maybe one day I update it and release as a separate project...

That's it!

Edit 2013/05/16: Simplified removeItem implementation and moved it into it's own section.

I’ve been using the excellent SuperTab Vim Plugin for a couple years, it works reasonably well (autocompletes based on words from all buffers, file names, tags, context, etc…) but it doesn’t work really well for text that is split by dashes - CSS contains lots of these… - so I started to get frustrated with it.

You can change the auto complete behavior with set iskeyword which also changes the behavior of standard motion commands like w, e, b (it changes the word delimiters) – which a find a PITA since I got used to these motions. My quick and dirty solution to the problem was to keep iskeyword with the minimal value as possible and only change it during InsertEnter. That way I can still use cw, ve, db to edit each fragment, autocomplete will work properly for words like foo-bar__baz, and you can still use W, B and E if you want to quickly jump around. For me that’s the best of both worlds!

function! KeywordsAll()
    setl iskeyword=@,48-57,192-255,\@,\$,%,-,_
endfunc

function! KeywordsBasic()
    setl iskeyword=@,48-57,192-255
endfunc

" improve the 'search word under cursor' behavior
nnoremap * :silent call KeywordsAll() * :silent call KeywordsBasic()
nnoremap # :silent call KeywordsAll() # :silent call KeywordsBasic()

augroup is_keyword
  " clear commands before resetting
  autocmd!
  " make sure `complete` works as expected for CSS class names whithout
  " messing with motions (eg. '.foo-bar__baz') and we make sure all
  " delimiters (_,-,$,%,.) are treated as word separators outside insert mode
  autocmd InsertEnter,BufLeave * :call KeywordsAll()
  autocmd InsertLeave,BufEnter * :call KeywordsBasic()
  " yes, we need to duplicate it on VimEnter for some weird reason
  autocmd VimEnter * nnoremap * :silent call KeywordsAll() * :silent call KeywordsBasic()
  autocmd VimEnter * nnoremap # :silent call KeywordsAll() # :silent call KeywordsBasic()
augroup END

And here are my other autocomplete settings:

set infercase
set completeopt=longest,menuone
set omnifunc=syntaxcomplete#Complete
set completefunc=syntaxcomplete#Complete
set complete=.,w,b,u,U,t,i,d

augroup omni_complete
  " clear commands before resetting
  autocmd!
  " Enable omnicomplete for supported filetypes
  autocmd FileType css,scss setlocal omnifunc=csscomplete#CompleteCSS
  autocmd FileType html,markdown setlocal omnifunc=htmlcomplete#CompleteTags
  autocmd FileType javascript setlocal omnifunc=javascriptcomplete#CompleteJS
  autocmd FileType python setlocal omnifunc=pythoncomplete#Complete
  autocmd FileType xml setlocal omnifunc=xmlcomplete#CompleteTags
augroup END

I’m not using any plugin to generate JavaScript or CSS tags so my code completion is mostly based on all words contained on all the open buffers. Because of the way I structure my code nowadays, I hardly need more than that.

PS: I don’t recommend Vim to a new developer for the same reasons as described in this post, even tho I can’t see myself using another editor nowadays… – here is my complete .vimrc + some links in case you are interested.

Edit (2013/04/25): changed autocmd to be triggered on BufEnter and BufLeave to improve complete across all open buffers.
Edit (2013/05/01): improved * and # behavior.

Discussions about modularity are recurrent. Some people say that each function should be a separate module/file/package; others say that methods should be contained by a package and grouped by similarity/concerns; and there is still a 3rd group that thinks that a single namespace is the way to go. I will try to explain the design decisions that influenced the creation and current structure of moutjs and why single function packages are not always the best solution.

How it started

It all started back in 2009, when I decided to extract and port some common methods that I used in different projects into reusable packages. I started by creating a stringUtils and arrayUtils namespaces and adding new methods as needed. The helpers grew at each project and after a few months I had more than 20 functions inside the stringUtils namespace (some of them pretty large since they handled HTML entities conversion), which means I had to load the 20+ functions even if I only needed a single method - keep in mind that I do mostly front-end development and at the time I was coding mobile sites very often, file size was a big concern.

// used a long (global) namespace to avoid name collisions
// loaded all methods even if not used by the app
MM.arrayUtils.forEach(arr, doSomething);
var slug = MM.stringUtils.hyphenate(myStr);

Going modular

At the end of 2010 I was working on bigger JavaScript projects (+10K LOC) and started to use RequireJS to manage my dependencies, and by doing so I was motivated to split my code into smaller files, that way I could keep the code organized and load only what was actually being used by the app. That enhanced my JavaScript development experience a lot, I was able to write apps with more than 50K lines of code with ease, code reuse increased exponentially at each project, no more conflicts when working with other devs and specially no more reliance on globals - I do a lot of projects that need to run inside bigger sites/apps, relying on globals is a path that usually leads to pain.

// require a single method (recommended)
var forEach = require('mout/array/forEach');
forEach(arr, doSomething);
// or the whole package if you want to (I rarely do this)
var stringUtils = require('mout/string');
var slug = stringUtils.hyphenate(myStr);

Why a single package?

The state of front-end Package Managers

One of the main reasons to keep mout as single package is that package management for the front-end is still in flux. Some people been using npm while others use bower/volo/jamjs, so it’s hard to get into a common ground. Adopting one package manager over another might cause some potential users to not use the lib, since that might not be their preferred approach or just not how they are handling dependencies. - node.js people, mind yourself that not everyone is writing node.js apps, so npm and cjs modules are not the silver bullets that you guys like to pretend they are.

Distributing a single package is easier for consumption in the browser, since you can just download a zip/tarball into the right folder and call it a day. In fact I’ve been using some very basic shell scripts to download/update my dependencies over the past couple years and it’s working pretty well for packages that have a shallow dependency tree.

Git submodules are a pain to maintain

The package manager isn’t the only reason, there is also the fact that maintaining multiple git repositories can be a huge PITA. Everyone knows that git submodules doesn’t work that well and there are some things that are just simpler when you deal with a single repository (mout contains ~200 methods). Things like scaffolding, automation and running tests is easier since you have less moving parts - single build script, single test runner, single CI server, etc.

The mout build script is responsible for keeping all packages up-to-date before running the tests, if a module doesn’t contain tests it creates a failing spec automatically to warn you. It also contains some scaffolding commands to create new modules based on templates and a command to help deploy the project. That is the kind of automation that is easier to implement if the project follows a sane structure.

PS: I know npm doesn’t require all packages to be separate git repositories (you don’t even need a public repository), but if they aren’t separate repositories then it probably shouldn’t be a separate package as well.

Consistency

The main reason why code reuse is such a hard thing to achieve is because most libraries/frameworks aren’t designed to work together and makes a lot of assumptions on how they will/should be used. Since everything is coded together there is a reduced chance of naming conflicts and you also increase the consistency/cohesion between all functions (including naming conventions). It motivates code reuse between internal modules as well.

Some bugs and enhancements affects multiple modules at once, having a decentralized issue tracker can lead to many duplicates and also makes it harder for users/maintainers to follow the progress. As an example we decided to borrow a feature from Lo-Dash on mout v0.4, the ability to use a shorthand notation on most array/object/collection methods, so you can do find(users, {name:'john'}) instead of find(users, function(u){return u.name === 'john'}). This change affected 18 modules and required 2 new methods (1 private). This is the kind of change that should be done across the board, all at once. Releasing 20 packages !== fun. If each package was maintained by different users it would surely not work since we could never get into an agreement if this feature should really be implemented or even coordinate a release date…

If each method accepts a different set of arguments (or different order) and/or are named following different conventions you will probably make more mistakes. Common conventions means less time spent reading the docs or fixing silly bugs.

Less bureaucracy

Since everything is part of the same package, it’s easier to handle the dependency on the “project context” and still require individual methods as needed. If every single function was a separate package you would need to list it twice, once on the package.json and another every time you require the module.

“Discoverability”

Since everything is part of the same package you increase the chance of the user to discover that feature. There are many functions that aren’t popular and the user would never find out they existed, or how useful they are. Sometimes you don’t know you need it until you see it. How can you find something if you don’t even know what you are looking for?

It means less time spent hunting for packages. You can trust that all functions have somewhat the same quality level and are meant to work together.

Project goals

I created mout with the intention of using it as a replacement to the JavaScript Standard Library, where you don’t need to worry about browser quirks and can use all methods in all environments (IE 7+) with a good amount of confidence.

Since it’s meant to be a “standard lib” you wouldn’t expect it to be scattered across multiple places.

Cross dependencies

There are a lot of cross dependencies between modules. Handling it between multiple separate projects would be a tricky thing, specially for browsers.

Dependency graph generated with node-madge (excluded packages to make it easier to identify real dependencies).

“Identity”

Multiple packages doesn’t hold any “identity” and probably won’t create a strong sense of “community”.

Why AMD as the authoring format?

The authoring module format is just a detail. It can be easily translated into any other module format if needed.

Since I do mostly front-end development it makes more sense to write the modules in a format that works in the browser without needing a build. It also makes the whole deployment process easier. Since most node.js modules are installed through npm, we can convert it into a node.js compatible format during npm publish and make sure that the users will get the files they need without any extra overhead (no performance or readability drawbacks). Since the browser package managers usually use the git repository as the source (don’t have something similar to npm publish) it’s better to leave the files on github always ready for browser consumption.

There are no silver bullets

mout have very specific goals and needs, that’s why it’s coded in this specific way. The reasoning described above surely doesn’t apply to all projects, in fact I believe it applies to the minority.

I truly believe that single function modules will become more popular in the following years, but it surely isn’t how I write most of my application code. Not all code need to be reused in different contexts, and modularity is not always an advantage (sometimes it can be an extra layer of bureaucracy). Consider the options and pick the one that fits better your needs.

My rule of thumb nowadays is that if something doesn’t help me it will probably slow me down. I won’t follow some specific convention/pattern/dogma just because other people say it’s the right thing unless I think it does apply to my own scenario. Working on a fast paced environment with many changes during the development process made me become more pragmatic about how I approach problems, same rule might not apply to yourself.

“It just works” is fantastic, when it really does just work. But it’s brutal when it doesn’t actually work. Then I prefer transparency. – @JohnDCook

Give it a try

mout contains many useful features, consistent API, good documentation and is being actively maintained. We also have an extensive set of unit tests to ensure correctness. Expect even more features in the coming months and a fast release cycle. We’ve been working hard to make it as awesome/reliable as possible. Check it out at http://moutjs.com and star/fork the project on github. We are also on the #moutjs channel on irc.freenode.net.

Further reading

• Keep your modules and functions small
• substack opinion about single function packages (external)
• Death to monolithic libraries (external)

I know that jQuery 2.0 will have the same API as 1.9, this wishlist would be for a future version of jQuery that doesn’t need to be backwards compatible (call it jQuery Harmony or jQuery 3.0 if you will).

Consistency

I used jQuery on most projects for the past 5 years and I still get confused with some methods. I think that a good part of it is because some methods/options are poorly named and also because most functions have a LOT of faux-overloads. The fact that every single method is in the same namespace and that everyone thinks that everything should be a plugin, amplifies this problem as well.

add()

What would you expect when you call a method add() on a collection? My initial thought would be that it append the new elements to the end of the collection, just like Array#push does. Of course if the collection is a jQuery collection I would be wrong.

var lists = $('ul');
var allLists = lists.add('ol');
console.assert( lists === allLists ); // false, it returns a new collection!

Since it returns a new collection concat or join would be better names.

map() / each() / filter()

Arguments order is reverse than what I would expect, there are native Array methods with similar names and different behavior.

// how it is
$('.foo').each(function(index, element){
    ...
});
// how I expect it to be
$('.bar').each(function(element, index){
    ...
});

I rarely need the index but I need a reference to the element 99% of the times. And no, don’t tell me to use this to reference the element (I avoid it).

It should also accept a 2nd argument to set the context (this keyword) value, just like the ES5 Array methods.

is() / not() / has()

Ok, this one used to get me all the time. Almost all methods inside the traversing category on the documentation returns new collections, they are basically ways to filter the matched elements, grab siblings/parent elements, add new elements to the collection – basically anything that changes the matched elements – but of course there are exceptions to the rule.

By looking at the names is, not and has you would expect the return value from the 3 methods to be similar, guess what? they aren’t. is() returns a boolean, not() and has() filters the collection. Very counter intuitive.

not() is the opposite of filter(), by looking at the name I would expect it to be the opposite of is(). Better name for not() would be reject(), exclude(), discard(), etc…

I also think that has() gives an idea that the return value will be a boolean: “does X has Y?”. This one might need a two word name to be descriptive, even a bad name like ifHas() would solve the return ambiguity. The method has() should be similar to is(), it should return true if any of the matched elements have a descendant that matches the selector or maybe even better, should be called hasDescendant().

contents() / children()

I’m not a big fan of method overload and I also don’t like booleans as arguments (boolean trap) but this is the case where I think a boolean on children() would be better than a new method named contents(). I have no idea what contents returns, is it a string? does it require any arguments? is it a setter or getter or both? Name it getChildren() and getAllChildren(), problem solved.

Better names

Descriptive names can reduce the need of a documentation, it also makes the API discovery process way easier, you can guess what the method does just by looking at the name. Besides the lack of consistency on the previous examples jQuery also contains many methods that are poorly named. Just to cite a few:

jQuery.inArray()

Why? I don’t even… A method called inArray returns an integer (-1 if not found), this should be called indexOf or return a proper boolean value, no excuses for it.

jQuery.proxy()

This method should be called bind since it is similar to the ES5 Function#bind, proxy is an overloaded term in programming (design pattern, proxy server, …) and should not be used to describe something that have a popular/alternative name.

jQuery.extend()

You are not extending an object, you are augmenting it with properties from another one. This is a helper for mixIns. mixIn or merge would be better.

toggle()

Toggle what? class name? display? visibility? state? Is this method really needed?

jQuery.param()

This name isn’t really descriptive; query, objectToQuery, serialize would be better. Note that serialize would conflict with a existing method but that method should also have a better name (serializeForm, serializeFormAsArray, formToQuery).

$.Callbacks

Callbacks are a dumbed down version of a Signal with a few mistakes.

Flags being a string is error prone and awkward.

// ops, typo and multiple spaces. silent failure.
var cb = $.Callbacks('once  memoy');

fireWith() is weird since all the callbacks will be called on the same context and it can cause conflicts, you need to know the structure of all the callbacks beforehand and it deceives the decoupling logic, the event dispatcher shouldn’t know about the handlers implementation… Setting context during add() would be better.

disable() and lock() seems redundant and doesn’t have options to re-enable/unlock.

Callbacks should be replaced by js-signals, better API, better implementation, more flexible and less error prone.

$.Deferred

Follow the Promises/A+ spec. kthx, bye.

Animation

Make it better, faster, stronger. The queue system is nice in some cases but most of the times it is a huge PITA. Multiple consecutive calls trigger multiple animations, I don’t think we should need to call stop(true) every time we want to toggle the animation. If you don’t know what I mean just check this jsbin.

I also think it should provide an easy way to reuse the methods without triggering all the hooks so I could tween any numeric values without overhead. There is no reason why the animation module should be tight coupled with the DOM.

This is a part of jQuery that I would probably throw away and start from scratch.

Ajax

Please fix this. Too many options and some really bad names, I always need to check the documentation to use it and I always commit mistakes that are hard to track, mostly due to misspelled/invalid options.

Just look at the documentation, 33 options! Nobody will ever remember all of them, that is fine, as long as the frequently used ones are easy to guess and if I pass an invalid option it tells me that I’m wrong, unfortunately that is not the case.

data sets which arguments should be sent together with the request (query string or POST body), so why dataType and dataFilter are related to the response? contentType is used to set the request content type. contents is used to parse the response… Please keep names consistent, if you use a prefix/word for the request don’t use it as well for the response.

If I had a penny for each time I try to use method: "POST" instead of type: "POST" I would have almost $1. In my head GET, POST, PUT, DELETE are request methods, not types.

ajaxError / ajaxSend / ajaxStop / ajaxError

These should be signals/$.Callback so you could add/remove listeners, set priority, etc:

jQuery.on.ajaxError.add(logAjaxError);
// later in the code we can remove listener
jQuery.on.ajaxError.remove(logAjaxError);

I rarely use this, but sometimes it can be useful for logging and/or for generic error handling. For debugging Charles Proxy and Dev Tools Network Panel are way more useful.

Less method overloads

Some jQuery methods have more than 5 overloads based on the arguments that are passed. Having optional parameters and accepting a couple different arguments types can make things simpler but it surely shouldn’t be abused. The jQuery() method is the biggest offender, you can pass selectors, elements, object, jQuery instance, function, HTML string… – This should be split into at least 3 distinct methods, being brief is not always a good thing.

My point is that it is harder to read the code afterwards if you aren’t familiar with the different signatures of the method. Discovering the API is also harder and requires constant checks on the documentation.

Modularity

The custom build (added on v1.8) was a good step forward but still not good enough. I don’t want to load the whole library just to use a few methods, I also don’t want to manually check what is being used and sometimes we only use a small subset of a “module”.

I know it is hard to split everything and that there are a lot of cross-dependencies on the internal code, but it just doesn’t feel right. On most projects I probably use less than 20 methods – filter, closest, toggleClass, remove and $ gets 70% of the job done.

I know I could use Google Closure Compiler Advanced Mode to remove the unused code branches but in some cases that isn’t possible. In the past couple years I worked on projects that required a substantial amount of JavaScript (20-50K LOC) and lazy loading some parts of the app was essential for the performance, creating an externs file can be tricky and not really easy to maintain in the long run, besides the fact that I use AMD modules on almost all projects which makes it even harder.

I would like to see complete modularity, being able to require a single method and use it as a standalone function:

var $ = require('jquery/$');
var foo = $('.foo');
// loading a new method would augment the `jQuery.prototype`
var find = require('jquery/dom/find');
foo.find('.bar');
// but also work as a standalone function
find(foo, '.bar');

That way it is clear that my module depends on methods XYZ and my build will take care of bundling only what is being used. You can also use a tool like node-madge to get some cool dependency graphs and help during refactoring.

By requiring individual methods you discourage the use of too many dependencies, which also have the added bonus of smaller source files and modules that take care of a single responsibility. I’ve been doing that for the past year with amd-utils and it’s working great.

Of course there should be a way to require the whole package at once for brevity:

// load whole jQuery package
require('jquery');
// or individual modules
require('jquery/dom');
require('jquery/css');
require('jquery/ajax');

Lazy users could still be lazy but would allow the freaks to control what they load and how they use it.

The list goes on…

I didn’t listed all the things, just the ones that bothers me more, but it should be enough to show that there are a lot of things to be improved and that lack of consistency is my main complaint. If you are a jQuery maintainer please consider a few of them for the future.

VanillaJS & Why I use jQuery

Yes, for modern browsers jQuery isn’t so relevant but it is still nice to have better abstractions, it shields the app from browser discrepancies and increases productivity. Nicholas Zakas gets into more details on The Problem with Native JavaScript APIs, worth a read.

jQuery is my library of choice for most projects (even if working by myself) mainly because it is popular. It’s easier to find someone to maintain/contribute, there are a lot of opensource plugins and components, bugs are spotted/fixed quickly since it’s being used by millions of sites, etc. It is also very productive after you get used to it…

I guess sometimes “worse” is really “better”.

Further Reading

• Stop Writing Plugins
• Avoiding the this keyword on jQuery related code
• Naming methods, properties and objects
• The rise of “worse is better” (external)

Travis is a free continuous integration server for open source projects that can be used to automate tests and help you deal with projects that have multiple contributors. If you are familiar with GitHub you probably seen their build status icons on a few projects before (on the image above). It can be used to test multiple languages like JavaScript, PHP, Python, Ruby, Java and many others. It also have options to notify the project maintainers every time the build status changes or on each commit. (email, IRC, campfire, etc)

It is really easy to setup it if your tests are already executed on the command line. If the tests needs a browser to work you can hook a headless browser like PhantomJS. - For my projects I’m just executing the tests on node.js for now since that should be enough to catch most errors. - Having a headless browser can help to double check if the code works on multiple environments.

Travis documentation is very clear and the amount of boilerplate is minimal, for a regular node.js project you just need a file named .travis.yml on the root folder containing:

 language: node_js
 node_js: 0.8

By default it will execute the npm test script for node.js projects. If you want/need you can execute multiple scripts like:

 script:
   - "echo Travis rocks"
   - "node build"
   - "npm test"

On amd-utils I added a pretest script that checks if all modules have specs (if it can’t find it will create a failing spec for the module) and update all packages/spec runner. I also added a script to check the code coverage of my tests (using Istanbul) to make sure pull requests (and my own commits) have a high code coverage.

 script:
   - "npm test --coverage"
   - "node ./node_modules/.bin/istanbul check-coverage --statements 90 --branches 90 --lines 90 --functions 90"

With the code above the integration test will fail if the code coverage is below 90%. This will ensure we have tests for every method and will help check if our tests are covering different scenarios - code coverage is just a metric to help you identify potential problems, it doesn’t really mean your tests are good enough, it just identify if the statement/line/function/branch was executed at least once, so beware, don’t trust it blindly. - I’m not setting the code coverage higher since amd-utils have some specific code branches that are only executed on old JS engines (specially IE). Check the last build report.

Travis is nicely integrated with Github, showing if a pull request passes the CI test, it is a good way to spot errors early.

The build status icon is also a nice indicator to add to the project README.md file.

I highly recommend it for projects with multiple contributors, will be using it on all open source projects from now on.

Automate repetitive tasks and make contribution easier, it will surely pay off in the long run.

Further Reading

• Travis CI homepage (external)
• Travis CI Documentation (external)
• Quality Code via Multiple Layers of Defense (external)
• JavaScript Code Coverage with Istanbul (external)
• Node.js Protip: Avoid Global Test Runners
• Node.js as a Build Script

Yesterday I pushed 2 new projects to github, was unsure if I was going to do it since maintaining opensource projects can demand a lot of time but heck, I’m looking for contributors and they can be useful to more people, so why not?

I used editors/IDEs that had a good code formatter for a while and ever since I started doing more JavaScript development I missed a code formatter as powerful/flexible as FDT. I know WebStorm has a very good support for JavaScript but nowadays I’m a Vim user and it’s really hard to make the switch. I wish I could have the same amount of settings on a command-line tool, that way it could be hooked into multiple text editors (Vim, Emacs, SublimeText, Cloud9, etc…), have an external configuration file (so it could be shared between team members) and used to batch-process files. Being written in JavaScript would also be a plus (so it could be used inside the browser and have more contributors).

At the beginning of 2012 I decided to look for tools that accomplished what I wanted but couldn’t find anything that was even close (jsbeautifier is not enough), so I submitted a feature request to escodegen, given that it had a good structure and was being actively maintained, I thought it could be a strong candidate. The months passed by and I didn’t had time to contribute to it (and forgot about), but most importantly, my opinion did change. – Nowadays I believe that a reliable code formatter should not rewrite the original source code, it should only modify the white spaces and line breaks while keeping all the original tokens (only non-destructive transformations). I also fell that it would increase escodegen complexity a lot and it is beyond the responsibility of the project (generate JavaScript from an AST).

During the process I tried to use node-falafel to traverse & modify the AST but it didn’t work as I needed – recursive walk started from root node and some nodes was traversed more than once – and it also didn’t had any information about original tokens, so I created a separate project to do the AST walk and manipulation. It’s called Rocambole – inspired by a popular Brazilian cake and also by node-falafel and node-burrito (rocambole is a sweet wrap).

Check both projects on Github and use the issue tracker for feature requests, questions and bugs:

• esformatter
• rocambole

Contributors are always welcome.

TL;DR: while is less verbose and more clear in many cases.

Less tokens per line

Lets take a very basic example into consideration:

for(var i = 0; i < 100; i++) {
    console.log(i);
}

Converted into a while loop:

var i = -1;
while(++i < 100) {
    console.log(i);
}

What bothers me more on the for statement is that you have too many things going on the same line. Variable declaration, conditional logic and another expression to increment the variable. I find the line while(++i < 100) way easier to read/understand than for(var i = 0; i < 100; i++), less tokens to grok and a single responsibility.

Another benefit that I see by moving the var declaration to outside the loop logic is that it makes it clear that variables aren’t bound to the loop scope (JavaScript only have block scope if you use the let keyword which isn’t standard). If you are enforcing manual variable hoisting and/or single var statement on your code guidelines the while loop will make even more sense.

Many operations can be executed in reverse order

Many types of operations can be executed in reverse order without affecting the end result. while loops are very succinct and clear when looping backwards:

var n = 100;
while (n--) {
    console.log(n);
}

Compared to a for loop that does the same:

for(var n = 99; n >= 0; n--) {
    console.log(n);
}

Notice that on the for loop you need to subtract 1 from the length to achieve same result (array indexes starts at zero).

PS: Some operations are slightly faster when executed in reverse since they avoid changing the size of the Array during the operations. (change it only once upfront)

Processing Array elements

It is very common to use for/while loops to process array items. It’s a common knowledge that we should avoid property lookups whenever possible to increase performance, so it’s a very common practice to cache the Array.length. By doing that the for declaration gets even more complex:

for(var i = 0, n = arr.length; i < n; i++) {
    console.log(arr[i]);
}

I would rather write it like this:

var i = -1,
    n = arr.length;
while (++i < n) {
    console.log(arr[i]);
}

Each line takes care of a single responsibility, less lines of code isn’t always a good thing.

If you are 100% sure that the array won’t contain falsy values (null, undefined, 0, false, "") you could make it even simpler:

/* jshint boss:true */
var cur, i = 0;
while (cur = arr[i++]) {
    console.log(cur);
}

Beware that falsy values will break the loop, use with care.

PS: I’ve been favoring Array#forEach, Array#map, Array#filter in many cases since I think it focus the program code on the actual problem and not the loop logic, but I still use plain loops in some cases to iterate over arrays.

RegExp.exec

The same pattern above could be used for methods like RegExp#exec:

var re = /\w+/g,
    match;
while (match = re.exec('== Lorem ipsum dolor sit amet ==')) {
    console.log(match);
}

This will execute the RegExp#exec method over the whole string until it can’t find anything that matches the pattern. It can simplify parsing logic a lot.

Getting “clever”

I’ve seen lots of people abusing the fact that you can omit the expressions on the for loop or that you can use the comma operator to do tricky things, but why not use the while statement instead?

// first and last expressions are optional
var i = 0, cur;
for( ; cur = arr[i++]; ) {
    // ...
}

By (ab)using the comma operator you can basically remove all the work from the while body and move it to the expression block.

// will execute until `cur` is falsy and/or `cur.doSomething()` retuns
// a falsy value
var i = 0, cur;
while( cur = arr[i++], cur && cur.doSomething() );

You can find a real working example of this concept applied to a very small snippet on the IE version detection script by padolsey and friends. I also use something similar on js-signals to execute all bindings of a signal until one of them stops the propagation (without the comma operator).

I’m not a fan of very clever tricks since I think they usually makes code harder to understand, but it is very good to know when/how to use these techniques since they can open your mind to simpler solutions in some cases.

Bonus: do-while

do-while is one of these features that I rarely need, but in some cases it can be useful. On a recent project I needed a greedy algorithm to search for the next empty cell on a grid that wasn’t adjacent to a similar item (couldn’t place product bottles next to each other before user starts filtering the grid items), the easiest way to solve it was to write a do-while:

do {
    // get next empty cell that can fit item
    cellIdx = this._getFitIndex(item, rowIdx, cellIdx);
    // check if cell isn't adjacent to a similar item (on current & prev rows)
    allowPlacement = this._checkPlacement(item, rowIdx, cellIdx);
} while (!allowPlacement && cellIdx !== -1);

After the loop I just had to check if allowPlacement && cellIdx !== -1 and place the item at that index. If false I created a new row on the grid and repeated the process.

On js-signals I use a do-while to implement a very simple sorted insert.

The do-while is nothing more than a sugared version of a while(true) which means I could totally live without it as well.

// same as previous example
while(true){
    cellIdx = this._getFitIndex(item, rowIdx, cellIdx);
    allowPlacement = this._checkPlacement(item, rowIdx, cellIdx);
    if ((allowPlacement && cellIdx !== -1) || cellIdx === -1) break;
}

top-level iterators

I’ve been using mout on almost all my projects for the past year and it is really great to access the array and object iterators as top-level functions:

var forEach = require('mout/array/forEach');
forEach(arr, function(item, i){
   console.log(i, item);
});

It would be nice if JavaScript had some kind of sugar for this kind of loops (since they are so common), maybe something that doesn’t need all the function boilerplate and that works over array and objects (anything that is iterable), I would probably suggest a syntax like this:

// sugar for Array#forEach and Object#forOwn
each(arr as [item, i]) {
  console.log(i, item);
}

On Harmony there is a proposal for the for of iterator, which is very similar:

// unsure if on Array we can also get the index
for(item of arr) {
  console.log(item);
}

If I was designing a language I would definitely include a feature like that, loops should have the least amount of boilerplate/distraction/landmines as possible.

Conclusion

I will probably avoid for loops on my own projects for the foreseeable future. while loops and ES5-like Array methods FTW (map, reduce, forEach, …)

The tool uses Esprima internally so it will keep the indentation, comments and it should work as long as the code can be parsed by Esprima. It will do as few replacements as possible to avoid undesired side effects.

Check the project repository for more info and please use the issue tracker for feature requests, bug reports and questions/feedback.

Related

• Namespaces are old school
• AMD is better for the web than CommonJS modules

The this keyword

The fact that you can call a method and pass a different context, by using Function#apply and Function#call, is one of the most powerful things for code reuse and also one of the most misunderstood features in JavaScript. jQuery (ab)uses this feature a lot, which in my (not so humble) opinion is not a very good design decision.

Newbies and code reuse

It is confusing for newbies and it favors code that is tight coupled with a specific scenario, the chance of reusing the same method latter is reduced.

Ambiguity and hidden dependency

The this keyword is too ambiguous, which makes the code harder to understand, you need to check how the method is invoked to understand what value this holds.

function injectMoreInfoLink(i){
    $(this).append('<a href="#/foo/'+ i +'">More Info</a>');
}
$('.foo').each(injectMoreInfoLink);

If you use an IDE/editor which gives some sort of code completion based on the parameters that the method accepts you wouldn’t know that you need to invoke the injectMoreInfoLink function as injectMoreInfoLink.call(element, i). Very counterintuitive. List all dependencies and avoid magic, it is going to be way easier to understand and reuse it in the future:

function injectMoreInfoLink(i, target){
    $(target).append('<a href="#/foo/'+ i +'">More Info</a>');
}
// works exactly the same way as previous example
$('.foo').each(injectMoreInfoLink);
// you can call it easily if needed
injectMoreInfoLink(12, someElement);

PS: jQuery got the arguments order wrong on the map and each callbacks. On the ES5 Array methods the arguments order is reversed (value comes before index). This always drives me crazy and the main reason why I usually don’t use the static versions of map and each to iterate over arrays.

Event Listeners, testability and bad practices

I strongly believe that the abuse of the this keyword influences bad practices, since it’s easier to do it the wrong way.

Just to point out how the this keyword works inside jQuery event listeners:

// the same behavior applies if using event delegation
$('.btn').on('click', function(evt){
    // target can be a child of ".btn" or ".btn" itself
    console.log(this === evt.target); // true or false
    // currentTarget is the ".btn" itself
    console.log(this === evt.currentTarget); // true
});

A common pattern:

function Foo(name){
    this.name = name;
    $('.bar').click(this.doAwesomeStuffOnClick);
}
Foo.prototype = {
    doAwesomeStuffOnClick : function(evt){
        evt.preventDefault();
        // misleading, unsure if `this` is the instance or an element
        $(this).toggleClass('awesome');
        // ops, won't work as expected
        // how do you access the instance name ??
        console.log(this.name); // undefined
    }
};
var myObj = new Foo('lorem ipsum');

Another option is to create a local var self and inline the doAwesomeStuffOnClick method - on this naive example that would work - but I would rather avoid this kind of pattern, it leads to code that is harder to maintain/reuse/test. Sooner than you expect you will have 5 nested functions and a huge pile of spaghetti code - been there, done that, no thanks.

function Foo(name){
    this.name = name;
    // this is an anti-pattern, avoid it as much as possible !!!
    var self = this;
    $('.bar').click(function(evt){
        evt.preventDefault();
        $(this).toggleClass('awesome');
        console.log(self.name);
    });
}
var myObj = new Foo('lorem ipsum');

I would probably implement it like this:

function Foo(name){
    this.name = name;
    // override method and bind to proper context
    this.doAwesomeStuffOnEvent = $.proxy(this.doAwesomeStuffOnEvent, this);
    $('.bar').click(this.doAwesomeStuffOnEvent);
}
// all methods are grouped on the prototype
// can be reused/tested/overwritten individually
Foo.prototype = {
    doAwesomeStuffOnEvent : function(evt){
        evt.preventDefault();
        this.doAwesomeStuff(evt.currentTarget);
    },
    doAwesomeStuff : function(target){
        $(target).toggleClass('awesome');
        console.log(this.name);
    }
};
var myObj = new Foo('lorem ipsum');

For most cases that might be overkill, but I’d rather code something that is easy to change than have to deal with a huge pile of mess, requirements change way more often than we expect.

More lines of code is not always a bad thing. If I ever need to execute the doAwesomeStuff on a different event type, let’s say a keypress, just need to add the new listener. If I decide to subclass this object I can override each individual method. That way you can also trigger doAwesomeStuff without passing an Event object, which depending on the scenario is a huge win. This also improves the testability of the code since every single concern is split into small chunks that can be called individually – unit testing FTW.

Too much this

I’m not a huge fan of plugins, in fact I think most people should not be writing plugins at all. If the this keyword is already confusing inside a simple code snippet, now think about a jQuery plugin.

// WARNING!! this code is useless and a very bad example of a plugin.
// we don't really need that many nested functions, it's just to point how
// confusing it can be to track what the `this` keyword means inside each fn
// PS: I've seen code like this many times
jQuery.fn.doFoo = function(className){
    // `this` points to the jQuery collection that was matched before calling
    // the `doFoo` method
    this.each(function(){
        // `this` is an individual element of the jQuery collection
        $(this).find(className).each(function(){
            // `this` is an individual element child of the collection
            $(this).append('bar');
        });
    });
    // we return the original collection so the user can "chain" multiple calls
    return this;
};
// FYI: it could be rewritten as `this.find(className).apend('bar');`

It can get even more confusing, now imagine a junior developer trying to debug or tweak this code… #chaos

Conclusion

Be explicit whenever possible, more lines of code and longer variable names aren’t always a bad thing, code completion/snippets are here to help, it usually pays-off in the long run. Code should be easy to read by humans, typing in most cases isn’t the bottleneck.

Further reading

• Stop writing plugins, start writing components
• Keep your modules and functions small
• A case against private variables and functions in JavaScript
• Naming this in nested functions (external)

am I the only one who find it “weird” that all (popular) node.js test frameworks uses a global install?

— Miller Medeiros (@millermedeiros) October 25, 2012

On this post I will try to explain why it’s an anti-pattern and show how to avoid global installs by using npm test instead.

Globals are evil!

Everybody knows that global variables are evil, but somehow nobody been talking about global installs of tools that doesn’t need to be installed globally to work. Very few Node.js modules should be installed globally, probably only tools like jshint (which can be used by text editors/IDEs) or anything that you expect to use together with other shell commands (ie. file system related tools). If your project depends on some third party code to work (including your tests) always favor local installs.

Local dependencies can be listed on the package.json file, so you keep track of the version, you can also commit them together with the project source code (making it easier for other devs to clone your project). It will reduce version conflicts and surely save you some headaches like “why do the tests work on my machine but not in others?”, which might be caused by a version conflict on the test framework.

If every single tool is installed globally the chance of name collisions will get extremely high. Please don’t do it unless you really need it.

npm test is your savior

Besides the fact of NPM being an awesome package manager it also has the very neat feature called scripts. It allows custom hooks to be executed before/after/during a certain action and comes with some good default behavior.

You probably want to run the tests multiple times and probably with the same arguments, so it’s way better to keep the test information inside the package.json file and reference the local bin file:

{
    "name" : "example",
    "version" : "1.0.0",
    "devDependencies" : {
        "jasmine-node" : "~1.0.26"
    },
    "scripts" : {
        "test" : "node node_modules/jasmine-node/bin/jasmine-node spec"
    }
}

Now you can run npm install --dev to install the devDependencies and every time you run npm test, it will execute the node node_modules/jasmine-node/bin/jasmine-node spec command, simple like that.

Automate ALL the things and avoid globals for a saner life.

Further Reading

• NPM Tricks
• package.json: An Interactive Guide
• node_modules in git