Jimmy Cuadra

GuerillaPatch: An interface for monkey patching objects for Ruby 1.9 and 2.0

Fri, 02 Nov 2012 19:03:55 -0700

At RubyConf this week, the first preview of the upcoming Ruby 2.0 was released. One of the new features is refinements, a way of adding new behavior to an object that only takes place within a certain scope. This allows a safer way to extend existing objects without screwing up code that may be depending on the original behavior. A common example of this is ActiveSupport, which adds extensions to many of the core classes. With refinements, these extensions can be added to a refinement module, which can then be "used" in other namespaces without affecting the object globally.

This is a powerful new feature, but I was curious how best to write library code that uses it in a way that is interoperable with Ruby 1.9. I created a gem called GuerillaPatch which provides a single interface that will extend an object with a refinement if run under Ruby 2.0, and fall back to simply modifying the class globally if run under 1.9.

Install with gem install guerilla_patch. The source code and usage examples are available on GitHub.

jQuery is not an architecture

Wed, 11 Jul 2012 01:26:23 -0700

There is no question about the enormous positive impact jQuery has had on front end web development. It removes all the pain of the terrible DOM API and provides utility functions for just about everything small applications need. But when your application starts to grow, you need to structure your code in a more organized way to make sure things are testable, maintainable, and that features are discoverable to both new members of your team and your future self, who may not be able to discern the business logic of your application from looking at a slew of selectors and anonymous function callbacks.

Although jQuery has many facilities, its main purpose is as an abstraction layer to create a single, developer-friendly API that hides the ugliness of bad APIs and browser implementation quirks. Because most of its methods involve selecting, traversing, and manipulating DOM elements, the basic unit in jQuery is the selector. While this has the benefit of making DOM interaction simple and easy for beginners to learn, it has the unfortunate side effect of making people think that anything but very trivial amounts of JavaScript should be organized around jQuery selectors.

In a very simple application or basic web page, e.g. a WordPress blog, tiny snippets of jQuery or a plugin dropped into the page may be appropriate. But if you're building something with an amount of JavaScript even slightly larger than that, things will get difficult to maintain quickly.

jQuery is no substitute for good application architecture. It's just another utility library in your toolbelt. Think of jQuery simply as an abstraction of the DOM API and a way to think about Internet Explorer less often.

To illustrate just how backwards the jQuery-selector-as-basic-unit approach is for a non-trivial application, think about how it compares to the structure of an object in an object-oriented paradigm. At the most basic level, objects consist of members and methods – stateful data and functions that perform actions to manipulate that data. Methods take arguments on which they operate. In selector-as-basis jQuery, you're effectively starting with an argument (the selector), and passing it a method in the form of anonymous functions. This is not to say that object-oriented software is the only correct approach to writing software. The problem is that jQuery tends to make the target of an action the focus and not the action itself.

Ways to improve architecture

There are a few simple ways to improve the architecture of your JavaScript code beyond what is shown in most jQuery literature.

Namespaces

Use a single global object to namespace all your code. Use more objects attached to your global object to separate your modules by their high-level purpose. This protects you from name collisions and organizes the parts of your application in a discoverable way. When your application grows very large, this makes it easier for people less familiar with the system to find where a particular widget or behavior is defined.

window.FOO = {
  Widgets: {},
  Utilities: {},
};

Modules

Use function prototypes or the module pattern to create pseudo classes for your modules. All the intelligence about what your application does should be encapsulated inside these discoverable modules. Use clear, straight-forward method names. By extracting your event handlers and other functions into named methods, they can be unit tested in isolation for a high level of confidence that your system behaves the way you expect. It's also much clearer what the module does when looking at code you haven't seen in a while.

FOO.Widgets.CommentBox = function (containerSelector) {
  this.container = $(containerSelector);
  this.container.on("submit", "form", this.addComment.bind(this));
};

FOO.Widgets.CommentBox.prototype.addComment = function (event) {
  // More logic here...
};

// Many more methods...

Instantiate your modules

Initialize your modules by constructing new objects, passing in the appropriate selectors as arguments. Assign the newly created object to a property on your global object. A good convention is to use properties beginning with capital letters for modules, and properties beginning with lowercase letters for instances of those modules. Using this approach, you can have multiple instances of the same widget on one page with explicit control over each individual instance. This is useful both for interaction between widgets and for development in the web inspector in your browser.

Deferring initialization until a module is instantiated programmaticaly gives you great flexibility when testing. You can isolate the effect of your module to a particular subtree of the DOM, which can be cleared out in a teardown phase after each test.

FOO.comments = new FOO.Widgets.CommentBox(".comment-box");

Just the beginning

These are just a few very simple examples of ways to structure your code as your application starts to grow. For even better object-oriented abstractions, consider using a library like Backbone, which, although usually associated with Gmail-style single page applications, is also very useful for writing well-organized JavaScript that focuses on behavior and application logic instead of selectors tying it to the markup and heavy chains of callbacks.

Please don't use Cucumber

Thu, 31 May 2012 19:52:56 -0700

Cucumber is by far my least favorite thing in the Ruby ecosystem, and also the worst example of cargo cult programming. Cucumber has almost no practical benefit over acceptance testing in pure Ruby with Capybara. I understand the philosophical goals behind behavior driven development, but in the real world, Cucumber is a solution looking for a problem.

The fact that Cucumber has gained the popularity it has in the Ruby community is outright baffling to me. All the reasons to use it that people give are theoretical, and I have never seen them matter or be remotely applicable in the real world. Cucumber aims to bridge the gap between software developers and non-technical stakeholders, but the reality is that product managers don't really care about Gherkin. Their time is better spent brainstorming all the various use cases for a feature and communicating this either verbally or in free form text. Reading (and especially writing) Gherkin is a waste of their time, because Gherkin is not English. It's extremely inflexible Ruby disguised as English. The more naturally it reads, the more difficult it is to translate it into reusable code via step definitions.

There are basically two extremes of Cucumber:

Writing Gherkin describing the feature at a very high level, and reusing few of the step definitions between features.
Reusing step definitions, resulting in a level of detail described in the Gherkin which is not useful for any of the stakeholders.

Everything in between is just a bad compromise of one or the other.

Gherkin is really just glorified comments. If you simply write free form comments above Capybara scenarios, you can convey the same high level information about what the test is doing and what the acceptance criteria are, without any of the overhead, maintenance cost, and general technical debt of Cucumber. This doesn't allow for the real red-green-refactor cycle from the outside in of the BDD philosophy, but in my experience, developers tend to avoid the test-first approach with Cucumber simply because it's so painful to use. If you're not really following BDD practices, and your non-technical stakeholders are not reading or writing Gherkin, Cucumber is wasting your developers' time and bloating your test suite.

The one advantage Cucumber offers over simply commenting Capybara scenarios is that, by tying the "English" directly to the implementation, it's impossible for the "comment" to rot. This is certainly a danger, as a misleading comment is worse than no comment at all. However, this benefit comes at an extremly heavy cost. I would argue that it should simply be the discipline of developers to make sure that any time a Capybara scenario is updated, the corresponding comment is read through and updated as necessary.

Whenever someone writes a criticism of a particular piece of software, there is always a group of people who respond by saying, "It's just a tool. If it works for you, use it. If it doesn't, don't." While I agree in theory, this is where the effect of the cargo cult becomes real and damaging. Some guy somewhere came up with this idea that seemed great in theory, and everyone jumped on the bandwagon doing it because it sounded cool and it seemed like something they should do. After a while, people choose to use it just because it became the status quo. They don't see that all the reasons a tool like Cucumber seemed like a good idea, based on some blog post they read 3 years ago, are not in tune with the real, practical needs of their project or their organization. And once that choice has been made, everyone has to live with the increasing technical debt and slowed, painful development it creates.

Constraints and compromises in ECMAScript 6

Sun, 22 Apr 2012 22:28:59 -0700

This past week I attended a talk by Dave Herman, an employee of Mozilla and member of ECMA TC39, who are in charge of the standard for JavaScript. Dave talked about a few of the features and improvements coming to JS in ECMAScript 6, including, what I think is the most exciting and desperately needed: the new module system.

I won't describe how the new module system actually works in this post, as that information is already available elsewhere (in particular at the ES Wiki). While this new module system looks great, I was concerned with the fact that it eschews the current community built around Node and its CommonJS module loading system. I asked Dave what the reasoning for this was. It boiled down to wanting to provide features for module loading which would not be possible using Node's current CommonJS system. Interoperability between client and server side JavaScript programs will eventually be achieved by converting existing code targeted for Node to the new module system.

While this may be a painful migration due to the amount of existing code using CommonJS, it seems like the best choice, given that the amount of JavaScript code targeting Node is dwarfed by the amount targeting the browser. Node will also be able to begin the conversion process fairly soon, as it only needs to wait for the implementation of ECMAScript 6 modules in V8.

Another feature Dave talked about was variable interpolation in strings via so-called quasi-literals. This feature is something very common in other high level languages, but to date JavaScript has relied on the concatenation of strings and variables with the + operator to achieve this. ES6, somewhat confusingly, uses the ` (backtick) to surround these quasi-literals and interpolates variables with ${varname} syntax. I was also curious about the reason for this awkward choice, given Ruby and CoffeeScript's precedence for using double-quoted strings with embedded expressions in #{}, but Dave had the answer. Backticks were chosen for backwards compatibility. If existing strings were to suddenly gain this ability, existing code on the web that happened to have literal occurrences of ${ in them would become syntax or reference errors. The most important constraint TC39 must embrace, unlike languages which compile to JavaScript, is that changes to the language must not break existing code on the web.

Backticks, even though they are often used to execute shell commands in other languages, were chosen simply due to limited set of ASCII characters remaining for new syntax. Again, the syntax they chose here is not ideal, but given the constraints necessary for advancing JavaScript without breaking the web as it exists today, it's a pretty decent compromise.

I'd like to thank Dave again for his talk. I'm looking forward to ES6!

New city, new job, new life

Sat, 11 Feb 2012 22:09:42 -0800

I haven't posted anything about myself in a while, so I'm happy to present this news: I have moved from San Diego to San Francisco, and am now happily employed by Change.org. This move was a long time coming. Many of my friends in college were from the bay area, as well as more friends I met through those friends. Everyone talked it up and seemed eager to return. In addition to the social motivation, San Francisco has a climate and culture that is much more akin to my taste. It's also one of the biggest tech hubs in the world, so career-wise it was a great choice as well.

I just finished my third week as a software engineer for Change.org. I'm happy to be spending my day working with technologies I love (Ruby, Rails, JavaScript, etc.), and even more so to be doing it to support a company with an awesome mission. Change.org has been receiving a lot of press lately and is growing very fast, and it's exciting to work for a company whose success I have a real interest in.

Other than one scary incident on a Muni bus, San Francisco has been a blast to live in so far. I'm enjoying the overwhelming amount of places to eat, the ease of getting around, the cool weather, and the cool people I've met so far. Meeting people in the Ruby and open source communities I've only followed online has me a bit star struck.

I will miss a few friends and the San Diego Ruby community I left behind, but San Francisco is clearly where I belong. Here's to a fantastic 2012 and beyond.

Bang goes 1.0, now with Hubot support

Thu, 15 Dec 2011 19:59:54 -0800

I just released version 1.0 of my command line utility, Bang. Bang is a simple key value store for quickly storing and retrieving text snippets. I talked about it in detail last month, so be sure to check out that post for samples of usage.

Version 1.0 merely fixes a few bugs and establishes the public API according to Semantic Versioning. Install Bang via NPM: npm install -g bang.

Perhaps the more exciting news is that you can now use Bang to smarten up your Hubot, GitHub's awesome chat bot! The Bang script for Hubot is available in the hubot-scripts repository. Clone the the repository, copy bang.coffee into your own Hubot's scripts, and add bang and shellwords to your package.json file. Deploy your Hubot and enjoy!

Bang: text snippets on the command line with Node.js

Mon, 14 Nov 2011 01:33:45 -0800

There's a great Ruby gem called Boom by Zach Holman for managing text snippets via the command line. I've used it since it was released and have even contributed to it a few times. But after using it for a long time, I realize that I don't really need the "lists" feature – the ability to store snippets with keys two levels deep. Because of Boom's syntax, I often accidentally create lists because I can't quite remember the name of the key I'm looking for.

I decided this was a good prompt for a new program, so I created Bang. Bang is a module for Node that gives you a very simple key value store with one level of depth. I use it to store all sorts of things: articles I refer to often, simple code snippets, Imgur links to animated GIFs, and strings with Unicode characters that are a pain to type.

For those, like me, who are experimenting with Node, CoffeeScript, testing using Jasmine, and annotated source using Docco, you will want to check out the source on GitHub to see some examples of all of these.

Install Bang

Install Node and npm.

$ npm install -g bang

Set a key

$ bang apples oranges

Get a key

$ bang apples
oranges

"oranges" is now copied to your clipboard.

Delete a key

$ bang -d apples

List keys

$ bang
  foo: bar
 blah: bleh
jimmy: cuadra
 bang: is rad

Feedback

I hope you enjoy Bang and find it useful. If you have a problem or suggestion, feel free to open an issue or send a pull request.

TL;DR

npm install -g bang
Check out Bang on GitHub
Read the annotated source code

CoffeeScript classes: under the hood

Fri, 14 Oct 2011 04:13:07 -0700

CoffeeScript has a very elegant mechanism for creating classes. If you're new to JavaScript, you may not be aware that there are no native classes, and that CoffeeScript classes are actually syntactic sugar for JavaScript's constructor functions and object prototypes. Most people are more familiar with the syntax offered by CoffeeScript, but it's a good idea to know what's happening behind the scenes.

The prototypal model

In JavaScript, there are no classes, in the classical sense. Objects are created and inherit directly from other objects. Functions are a type of object, and when invoked with the new operator, create a new object which use the function as a constructor. This new object has a hidden link to the prototype property of the constructor function that establishes its inheritance. If you attempt to access a property on the new object that doesn't exist, JavaScript will follow the inheritance chain to the constructor's prototype and use the value it finds there.

When you create a class in CoffeeScript, you're really creating a constructor function. Each instance method in the class is actually a property of the constructor's prototype.

A simple class

Let's take a look at an example class, Bear. A bear is very simple. It has one property, name, and one method, attack. A class delcared with the class keyword creates an empty constructor function. The class definition is followed by an object defining the properties of the constructor's prototype. Each key in the object becomes a property on the prototype. The special key constructor becomes the body of the constructor function itself.

class Bear
  constructor: (@name) ->

  attack: ->
    "#{@name} the bear attacks with his bare paws!"

oswalt = new Bear "Oswalt"
console.log oswalt.attack()
# Oswalt the bear attacks with his bare paws!

Bear defines a simple constructor which takes one argument, the bear's name, and assigns it to the name property of the instance. The attack method simply returns a string saying the bear is attacking. We instantiate a new Bear named "Oswalt" and log the results of his attack method. This outputs "Oswalt the bear attacks with his bare paws!" to the console. Let's take a look at how CoffeeScript translates this into JavaScript. (I've left out some closures and added whitespace for clarity.)

var Bear, oswalt;

function Bear(name) {
  this.name = name;
}

Bear.prototype.attack = function() {
  return "" + this.name + " the bear attacks with his bare paws!";
};

oswalt = new Bear("Oswalt");
console.log(oswalt.attack());

As we can see, the Bear class is really just a function named Bear. It takes one argument and assigns it to the new instance's name property. The attack method is just a function assigned to the attack property of Bear's prototype. We instantiate an object by calling new Bear and passing it the bear's name. When we attempt to access the attack property of the new object, JavaScript sees there there is no such property, and travels up the hidden link to the class's prototype, where it finds the method we want and executes it.

Inheritance

CoffeeScript's class syntax is a bit cleaner than the compiled JavaScript, but ultimately not that different. Where CoffeeScript classes really shine is in abstracting away the clunky steps required to produce classical inhertiance via the prototypal model. Let's extend Bear to see how it works.

class BearWithChainsawPaws extends Bear
  attack: ->
    super + " BY THE WAY, HIS PAWS ARE CHAINSAWS."

rodrigo = new BearWithChainsawHands "Rodrigo"
console.log rodrigo.attack()
# Rodrigo the bear attacks with his bare paws! BY THE WAY, HIS PAWS ARE CHAINSAWS.

This new BearWithChainsawPaws class is a child class of Bear. It overrides the attack method but does not change the constructor. Note that the new attack method uses super to call Bear's version of attack. This is very useful, because there isn't a direct equivalent of super in JavaScript, as you can see in the compiled code (again modified for clarity):

var Bear, BearWithChainsawHands, rodrigo;

var __hasProp = Object.prototype.hasOwnProperty;

var __extends = function(child, parent) {
  for (var key in parent) {
    if (__hasProp.call(parent, key)) {
      child[key] = parent[key];
    }
  }

  function ctor() { this.constructor = child; }

  ctor.prototype = parent.prototype;
  child.prototype = new ctor;
  child.__super__ = parent.prototype;

  return child;
};

function Bear(name) {
  this.name = name;
}

Bear.prototype.attack = function() {
  return "" + this.name + " the bear attacks with his bare paws!";
};

__extends(BearWithChainsawHands, Bear);

function BearWithChainsawHands() {
  BearWithChainsawHands.__super__.constructor.apply(this, arguments);
}

BearWithChainsawHands.prototype.attack = function() {
  return BearWithChainsawHands.__super__.attack.apply(this, arguments) + " BY THE WAY, HIS PAWS ARE CHAINSAWS.";
};

rodrigo = new BearWithChainsawHands("Rodrigo");
console.log(rodrigo.attack());

There's a lot happening here, so let's take it a bit at a time.

The first thing to notice here is that CoffeeScript has generated some boilerplate above the classes themselves that wasn't there in the first example. __hasProp is just a shortcut for Object.prototype.hasOwnProperty. Since it's used in a loop in the following function, this is a bit more performant. It's not particularly important in understanding how inheritance works, however. The real meat is the next function.

__extends is a helper function that sets up one class to inherit from another. The for...in loop copies all the class-level methods from the parent to the child. In this particular case, our classes have only instance methods, but if we were to have defined a class property, say Bear.awesome = true, then the loop would copy true into BearWithChainsawPaws.awesome.

The second half of __extends sets up the prototype link (which contains the instance properties and methods) from the child to the parent. At its simplest, prototypal inheritance is achieved by assigning an instance of the parent to the child's prototype. __extends uses a bit of indirection to both establish this link, and to correctly assign the constructor property for all instances of the child. This property points back at the constructor function itself, and is necessary for the instanceof operator to give the desired result. The intermediate ctor method is used to for this purpose.

Lastly, a __super__ property is added to the child class, which establishes a reference to the parent's prototype. Without this, achieving super would require manually calling the parent class by name, which is error prone and not particularly maintainable. Inside BearWithChainsawHands's methods, we can see this reference to __super__ being used to call Bear's methods through the magic of apply – a method which invokes one object's method within the context of another object.

The point

While I do think CoffeeScript is pretty rad, the point of this post is to aid in understanding of what CoffeeScript is doing behind the scenes to provide its niceties. It uses good, clean JavaScript to abstract away what, to many, is an awkward approach, and in doing so, teaches a great deal about how JavaScript works.

ECMAScript 5: Array methods

Wed, 12 Oct 2011 00:02:57 -0700

This is the third and final part of my series on ECMAScript 5. In part one, we looked at new methods for object creation and property definition. Part two focused on tamper proofing objects. I'll now provide a quick overview of the new high level array methods.

Unlike the new methods discussed in the first two parts, the methods here are all reproducible using JavaScript itself. Native implementations are simply faster and more convenient. Having a uniform API for these operations also promotes their usage, making code clearer when shared between developers.

Search methods

Array.prototype.indexOf

indexOf provides an easy way to determine whether or not an object is in an array. It returns the first index at which the item was found, or -1 if it was not found at all. Strict equality is used to determine that an item is present in the array. An optional second argument can start the search at an index other than 0.

var arr = ["apple", "banana", "carrot", "apple"];

arr.indexOf("apple"); // 0
arr.indexOf("daikon"); // -1

Array.prototype.lastIndexOf

Identical to indexOf, but returns the last index at which an item is found, if at all.

var arr = ["apple", "banana", "carrot", "apple"];

arr.lastIndexOf("apple"); // 3

Iteration methods

Array.prototype.forEach

Ever seen this before?

for (var i = 0, l = arr.length; i < l; i++) {
  doSomething(arr[i], i, arr);
}

There is now a clean, high level way to do this with forEach. The method accepts a callback which will be executed once for each item in the array. The callback receives three arguments: the value of the current iteration, the index of the current iteration, and the array itself. The following is equivalent to the above:

arr.forEach(doSomething);

An optional second argument specifies the value of this within the callback.

Array.prototype.every

every checks every element in an array against a condition, by means of a passed in function. If any of the items in the array cause the function to return a falsy value, every returns false. If they all return truthy values, every returns true. Like forEach, an optional second argument supplies a value for the callback's this, and the callback itself will receive the same three arguments.

var arr = ["apple", "banana", "carrot", "apple"];

arr.every(function (value, index, array) { return value.length > 1; }); // true
arr.every(function (value, index, array) { return value.length < 6; }); // false

Array.prototype.some

some is similar to every, but the passing condition is that at least one callback returns true, rather than all of them.

var arr = ["apple", "banana", "carrot", "apple"];

arr.some(function (value, index, array) { return value.length < 6; }); // true

Transformation methods

Array.prototype.map

Mapping is the most common transformation. It loops through an array, running a function and creating a new array built from the return values of each iteration. map takes the same optional second argument and receives the same callback arguments as the iteration methods.

var names = ["Abigail", "Bongo", "Carlitos"];

names.map(function (value, index, array) {
  return value + " Jones";
});
// ["Abigal Jones", "Bongo Jones", "Carlitos Jones"]

Array.prototype.filter

Filtering is like mapping, but creates a new array containing only the items of the original array that return a truthy value from the callback. filter takes the familiar optional argument and its callback receives the usual suspects.

var names = ["Abigail", "Bongo", "Carlitos"];

names.filter(function (value, index, array) {
  return value.length > 5
});
// ["Abigail", "Carlitos"]

Array.prototype.reduce

reduce is used to melt the items in an array down to a single value by the operations performed in its callback function. The callback takes the usual three iteration arguments, but is prepended with an extra argument, the value of the previous iteration's result. By default, the first iteration is effectively a no-op, so the calculation begins with the array's first value as the accumulated result and the array's second value as the current iteration. This is probably best illustrated with an example:

[10, 20, 30, 40, 50].reduce(function (accum, value, index, array) {
  return accum + value;
});
// 150

On the first iteration, accum is 10 and value is 20. The return value of accum + value becomes accum on the next iteration of the loop.

reduce can also take an initial value for accum as a second argument. When invoked this way, the first value in the callback is the first item in the array:

[10, 20, 30, 40, 50].reduce(function (accum, value, index, array) {
  return accum + value;
}, 50);
// 200

Array.prototype.reduceRight

reduce's sibling, which performs the same behavior and accepts the same arguments, except it iterates beginning with the rightmost item in the array and moves left. If not specified with a argument, the initial value of accum is the last value in the array, and the initial iteration value is the second to last.

[10, 20, 30, 40, 50].reduceRight(function (accum, value, index, array) {
  return accum - value;
});
// -50

ECMAScript 5 is full of goodness

ECMAScript 5 packs lots of new, useful features into JavaScript which speed up both development and performance of code. The new APIs are implented in the most recent versions of Chrome, Firefox, Safari, and (*gasp!*) Internet Explorer, so I encourage you to start using these new APIs today!

Extractor.js: simple global object management for JavaScript

Fri, 16 Sep 2011 01:19:10 -0700

I was messing around with CoffeeScript and Jasmine this evening and put together a very small library called Extractor. Here's the idea:

Everyone hates the global object in JavaScript, and care must be taken to manage potential variable name conflicts. Extractor works as a proxy for the global object, allowing library developers to register their libraries without touching the global object. Developers who use the library can then extract it into a variable name of their choice, possibly never touching the global object at all. The effect is similar to jQuery's noConflict function, but is used more like Node's require.

For more information (including usage examples), check out Extractor on GitHub.