Google Authorship on Giant Robots

You may have noticed a recent addition to our blog posts. We concluded an experiment to add a “Written by [Author Name]” byline and link the author’s name to their Google+ profile.

Google calls this Authorship. It is a feature that lets you verify that you are the author of some content, such as a blog post. It is kind of like a microformat that Google uses in its search algorithms. It also causes an author’s face to show in Google search results:

We take the following one-time steps to set up Google Authorship for each author on our blog:

1. Get a Google+ account.
2. Verify our email address for the domain, which will automatically add you as a collaborator of that website on Google+.

Now, whenever we author a post for one of those websites, we take the following steps:

1. Add a byline that has a link like Written by <a rel='author' href='http://plus.google.com/GOOGLE_PLUS_ID'>AUTHOR NAME</a>..
2. Link back to the article from our Google+ profile.

The links in both directions are help to confirm authorship of the article.

We can then see statistics on impressions, clicks, click-through rates, and average position in search results for pages for which we are the verified author:

Google Authorship is a nice way for us to better understand how our content appears in Google searches as well as expose our content to a wider audience.

Written by Caleb Thompson.

Two gotchas every CoffeeScript and Backbone.js developer should know

If you’re a Ruby developer working with Rails, at some point you’re going to need to work with JavaScript. While the two languages have many similarities, the fundamental differences in their object models can be quite jarring. CoffeeScript helps to provide a more Ruby-like syntax, but if you’re not careful you can introduce bugs to your code in surprising ways.

Let’s look at an example. Let’s say we have an expensive operation, and need to cache the result. In CoffeeScript, we might write the this code as:

class GiantRobot
  smashCache: {}

  smashInto: (other) =>
    @smashCache[other] ||= @expensiveCalculations(other)

However, this code leads to a surprising problem when we start smashing things together.

ralph = new GiantRobot()
voltron = new GiantRobot()

ralph.smashInto(optimusPrime)   # => not cached
ralph.smashInto(optimusPrime)   # => cached
voltron.smashInto(optimusPrime) # => cached?!

To see why this occurs, we need to take a look at how objects work in JavaScript. Unlike Ruby, JavaScript has no concept of classes. Instead it constructs its objects using prototypes. If you’re writing your code in CoffeeScript, you can almost always ignore this fact, and write your code as if you were in Ruby or Python. In this case, however, CoffeeScript is making our problem less apparent, so let’s take a look at what this code looks like using plain JavaScript.

function GiantRobot() {}

GiantRobot.prototype.smashCache = {};

GiantRobot.prototype.smashInto = function(other) {
  if (!this.smashCache[other]) {
    this.smashCache[other] = this.expensiveCalculations(other);
  }
  return this.smashCache[other];
};

Specifically, our problem stems from the fact that setting smashCache on the prototype may not work the way you’d think.

How prototypes work

When we create ralph with, ralph technically has no smashCache property. When we do this.smashCache, JavaScript looks for that property on ralph, followed by ralph’s prototype, then ralph’s prototype’s prototype, and so forth until it finds something that has the smashCache property.

JavaScript provides us a way to see this in action, using the hasOwnProperty method.

ralph.hasOwnProperty('smashCache')                # => false
GiantRobot.prototype.hasOwnProperty('smashCache') # => true

So when we call this.smashCache, we are always getting back GiantRobot.prototype.smashCache, which means when we mutate it, we are mutating the same instance of smashCache that is used by every instance of GiantRobot. This is only an issue when we’re talking about arrays and objects.

ralph.smashCache = 'some value'
# Variable assignment sets the property directly on the instance
ralph.hasOwnProperty('smashCache') == true

Avoiding mutating the prototype

So how do we get around this? Ironically, the answer is simply to make our original example look more like our Ruby code.

class GiantRobot
  constructor: ->
    @smashCache = {}

Now each instance will have it’s own separate smashCache, and all is well with the world.

Backbone.js gotcha: Mutating the defaults object

A similar problem exists in Backbone.js when using the defaults object on your models.

class RobotProfile extends Backbone.Model
  defaults:
    images: []

  addImage: (newImage) ->
    @get('images').push(newImage) # => Mutates a shared instance

The solution for this problem is even simpler. If we change the defaults property to be a function that returns the same hash, Backbone will call it every time a new instance is created.

class RobotProfile extends Backbone.Model
  defaults: ->
    images: []

Now our images array will no longer be shared across multiple instances, and we can mutate to our heart’s content.

Written by Sean Griffin

How to write a great README

Leadership is often defined as having the ability to make others want to do what it is that you would like them to do. You want people to want to use your software, and often their first introduction will be through the README in the source code or on the project’s GitHub page.

The Basics

There are of course components to a technical document that make it more effective. Describe what it is that your project makes easier. Provide code examples detailing how the use of the library. Document the installation process. These are the basic elements which define a README.

Creating a great face for your project, however, requires still more.

Don’t get lazy just because this is for developers

Technical writing is still writing, and need not be dry and boring. Just as if you were writing an essay or blog post, you should strive to grab the attention of your reader early. This can be easily accomplished with a well-written introductory paragraph. Use strong or emphasised text to give a short description of what the software does, such as “Receive emails in your Rails app”. You can also use an image which relates to the functionality of your library or alludes to some pun in the name.

Your readers will most likey view your README in a browser. Please keep that in mind when formatting its content. Put the name of the library in an <h1> at the beginning of the file. Categorize content using two or three levels of header beneath. Make use of emphasis to call out important words. Link to project pages for related libraries you mention. Link to Wikipedia, Wiktionary, even Urban Dictionary definitions for words of which a reader may not be familiar. Make amusing cultural references. Add links to related projects or services.

The code matters

Besides speaking English, your readers also understand code. Developers love to see code samples, and a few lines of syntax highlighted source are worth a thousand words. plataformatec/simple_form does an excellent job of providing code examples as well as explanations for nearly every setting and interface call. Besides being extremely greppable, simple_form’s README is the top Google hit for nearly all simple_form searches.

Be aware that sometimes the reason someone is visiting your project’s page is that they have a problem. If you know about persistent issues, such as resolving a functional dependency, call that out in a section of its own and provide a solution or workaround. Right in the README. Yeah. A great example of one such issue is thoughtbot/capybara-webkit’s dependency upon Qt. Because a gem cannot satisfy this dependency, we added a notice about installation issues to the README.

You are also encouraged to add “badges,” such as Travis CI’s or Code Climate’s to your README, but remember that they reflect on your project—a passing build with high quality code attracts developers to your library, while a failing master build can give them pause.

Written by Caleb Thompson.

Sandi Metz’ rules for developers

Back in January, Sandi Metz introduced her rules for developers in a Ruby Rogues podcast episode episode. Around the time Sandi’s rules were published, the team I am on was starting a new project. This post details the experience of that team applying Sandi’s rules to the new application.

The rules

Here are the rules:

1. Classes can be no longer than one hundred lines of code.
2. Methods can be no longer than five lines of code.
3. Pass no more than four parameters into a method. Hash options are parameters.
4. Controllers can instantiate only one object. Therefore, views can only know about one instance variable and views should only send messages to that object (@object.collaborator.value is not allowed).

When to break these rules

Paraphrasing Sandi, “You should break these rules only if you have a good reason or your pair lets you.” Your pair or the person reviewing your code are the people who you should ask.

Think of this as rule zero. It is immutable.

100-line classes

Despite the large number of private methods we wrote, keeping classes short proved easy. It forced us to consider what the single responsibility of our class was, and what should be extracted.

This applied to specs as well. In one case, we found a spec file ran over the limit which helped us realize we were testing too many features. We split the file into a few, more focused, feature specs.

That made us realize that git diffs wouldn’t necessarily show us when we exceed 100 lines.

Five lines per method

Limiting methods to five lines per method is the most interesting rule.

We agreed if, else, and end are all lines. In an if block with two branches, each branch could only be one line.

For example:

def validate_actor
  if actor_type == 'Group'
    user_must_belong_to_group
  elsif actor_type == 'User'
    user_must_be_the_same_as_actor
  end
end

Five lines ensured that we never use else with elsif.

Having only one line per branch urged us to use well-named private methods to get work done. Private methods are great documentation. They need very clear names, which forced us to think about the content of the code we were extracting.

Four method arguments

The four method arguments rule was particularly challenging in Rails, and particularly in the views.

View helpers such as link_to or form_for can end up requiring many parameters to work correctly. While we put some effort into not passing too many arguments, we fell back to Rule 0 and left the parameters if we couldn’t find a better way to do it.

Only instantiate one object in the controller

This rule raised the most eyebrows before we started the experiment. Often, we needed more than one type of thing on a page. For example, a homepage needed both an activity feed and a notification counter.

We solved this using the Facade Pattern. It looked like this:

app/facades/dashboard.rb:

class Dashboard
  def initialize(user)
    @user = user
  end

  def new_status
    @new_status ||= Status.new
  end

  def statuses
    Status.for(user)
  end

  def notifications
    @notifications ||= user.notifications
  end

  private

  attr_reader :user
end

app/controllers/dashboards_controller.rb:

class DashboardsController < ApplicationController
  before_filter :authorize

  def show
    @dashboard = Dashboard.new(current_user)
  end
end

app/views/dashboards/show.html.erb:

<%= render 'profile' %>
<%= render 'groups', groups: @dashboard.group %>

<%= render 'statuses/form', status: @dashboard.new_status %>
<%= render 'statuses', statuses: @dashboard.statuses %>

The Dashboard class provided a common interface for locating the user’s collaborator objects and we passed the dashboard’s state to view partials.

We didn’t count instance variables in controller memoizations toward the limit. We used a convention of prefixing unused variables with an underscore to make it clear what is meant to be used in a view:

def calculate
  @_result_of_expensive_calculation ||= SuperCalculator.get_started(thing)
end

Great success!

We recently concluded our experiment as a success, published results in our research newsletter, and have incorporated the rules into our best practices guide.

Written by Caleb Thompson.