Everyone has a lot of ideas for new stuff, as developers we are blessed to be able to bring some of these ideas to life. More often than not, though, we aim too high and quit before we even get started because of how daunting a task it might be. Other times we are doing so much at work already, that we just want a break.

In any of the cases trying new things will do you good. Try a new language or technology that excites you. You’ll learn new things that can be used in your daily job, or at least have fun. If teaching is your thing, there’s also the benefit of learning how to be a newbie again, which gives you perspective.

Starting something

Starting something is the hardest part, I always fear that I get too invested in a project that ends up to be a piece of crap. Turns out that a lot of times it’s when you don’t care if it is crap or not that the best things come into existence. There’s is an entire conference dedicated to instigate the Ruby community to build more strange things, because some of them will be great. It’s called Keep Ruby Weird, check it out.

A good way to start creating things is to think of what you do all day and try to automate (partly or completely) a small part of it. It’s likely that your problems will be shared by other people around the world, or at least your coworkers.

I did that and created something called Github Nice Guy.

Github Nice Guy

The problem I decided to tackle was the fact that pull requests are forgotten. This can happen because you lost interest in the project, the project is deprecated or relocated, etc…

My idea to solve this is described in the README as:

Github Nice Guy is a small Ruby script that fetches the open pull requests for a given user (or organization) and sends a weekly friendly reminder with links to them to whoever you think should know about it.

The coolest thing about this project, in my opinion, is that it took less than 30 minutes to get done (the first version at least). This is not because I’m an awesome developer or have mad typing skills, it’s mostly because it was just a couple of gems put together in a very shady way that kind of worked most of the times. But I learnt new things about the Github API (and how awesome it is), sending mails from a ruby script and integrating ruby scripts with whenever.

There’s nothing really fancy about it, but I got to try new things without a lot of commitment, and as a bonus got a small service that is now running in my company.

Conclusion and stuff

The main thing to get from this post (if there is one) is that you should see the resulting “product” as a bonus, the path to get there is what really counts.

This path can be miles long or inches short, that’s up to you, but building something that helps you out on what you do everyday is a good way to start gaining momentum.

ZSH

This is post is not about ZSH, but it is awesome and you should install it. All the configs will assume you are using it, but surely there are ways of doing the same for your shell of choice.

Hub

hub is a command line tool that wraps git in order to extend it with extra features and commands that make working with GitHub easier.

This is the description taken straight out of the project’s README. Hub is written by the guys at Github, so it is very much compliant with everything on the site. As of recently you can install it with Homebrew (non-mac users will have to compile it manuallly, I believe).

1

brew install --HEAD hub  # For the 2.x version

Now you can use hub and all it’s powers. The sane thing to do though, is to alias git to hub, which works perfectly as hub will delegate all non-hub commands to git.

Just open your .zshrc and add the alias:

1

alias git='hub'

When you brew install hub you will see that it installs completion files to you system.

1
2

zsh completion has been installed to:
  /usr/local/share/zsh/site-functions

If you run echo $fpath on your terminal that path should be there. fpath stands for functions path and you can store you functions in any directory listed in fpath. Read more about zsh functions here.

This will provide auto-complete functionality for all your git needs.

If you are like me, though, and git is the command you use more often (about 30% of the time in my case), you will probably want to alias it to something shorter, such as g.

1

alias g='git'

So now g maps to git which maps to hub. Great! We have, however, introduced an issue. Auto-complete is broken. That is because the git auto completion function is only expecting git or gitk as commands to auto complete.

You can add g to that set easily enough. Again, open your .zshrc and add compdef g=git.

You should have everything ready to go.

Git commands

Hub adds some really nice things, but what about those specific commands you love to use? At some point all of us have added commands as aliases in gitconfig.

1
2

[alias]
    ia = add --intent-to-add -A

This is not inherently bad, but it can go out of hand pretty quickly. Moreover, you don’t really have a lot of scripting power with these aliases. As you might have guessed by now, there is a better way of doing this and it is so cool that even some of the builtin commands use this strategy.

The basic idea is that any executable script on you PATH that is named git-some-name will be available as a git subcommand, which means you could do git some-name to run the script.

Git is so awesome that it even adds them to git help -a under the title “git commands available from elsewhere on your $PATH”, which will then power the auto completion, so that will also work for any command you add.

Going back to our example, there’s a couple of things to do to remove it from an alias into a command, add a directory to the PATH and create a script on that directory.

1
2
3

mkdir -p ~/dotfiles/git_commands
export PATH="$HOME/dotfiles/git_commands"  # Also add this to you zshrc, to persist it
echo "git add --intent-to-add -A" > ~/dotfiles/git_commands/git-ia

You should now be able to remove the alias from the gitconfig and still be able to run git ia.

Bonus round

Git will just grab the scripts that follow the aforementioned convention and run them. That means that as long as the shebang is correctly set, you can write a script in any scripting language.

Here’s one in ruby:

1
2
3

#!/usr/bin/env ruby

puts "Hello"

Just name it git-hello, put it in your git_commands directory and you should be able to type g hello and have git say “Hello” back.

Further reading

If you want to check some actual examples you can do it in my dotfiles or in Wynn Netherland’s dotfiles. This post was inspired by a talk given by Wynn at the DallasRB meetup, so do check his stuff.

Setting up the environment

The first thing to do is to call a function to set up our environment whenever we open vim, open a file on a new buffer or open a new file.

1

autocmd! vimenter,BufReadPost,BufNewFile * call SetupEnv()

That function will then check the current path and conditionally load config files.

1
2
3
4
5
6

function! SetupEnv()
  let l:path = expand('%:p')
  if l:path =~ 'project-name'
    source ~/.vim/project-configs/project-name.vim
  endif
endfunction

The project-names don’t have to be the same, but I find it makes sense if they do. And they usually refer to the root directory of the project.

The specific configs

We can the add regular vim configs the project-name.vim config file. Something that I find useful is to map shortcuts to commonly used directories (kind of a poor man’s Rails.vim :R).

1

cnoremap %a <C-R>'app/resources/scripts/apps/

Now every time you write %a in the command line it will be replaced with app/resources/scripts/apps/. So you can just :e %a and auto complete your way into the file you want.

You can also add other settings such as number of spaces per tab, which may vary from project to project. It’s as easy as:

1
2

set tabstop=2
set shiftwidth=2

If you’ve never heard of it, Rust is a language championed by Mozilla that aims at replacing C++ as the language in which Firefox in written.

While learning Rust I came across the Rust for Rubyists book by Steve Klabnik, which I recommend, and on that book there is small program that shows how to create different kinds of monsters with the same interface. I tweaked it a bit and implemented it in Ruby as well, so it can be compared.

The Ruby version

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

class IndustrialRaverMonkey
  def initialize
    @life = 100
    @strength = 20
    @charisma = 10
    @weapon = 50
  end

  def attack
    puts "The monkey deals #{@strength} of damage"
  end
end

class DwarvenAngel
  def initialize
    @life = 100
    @strength = 50
    @charisma = 70
    @weapon = 50
  end

  def attack
    puts "The angel deals #{@strength} of damage"
  end
end

def call_attack(monsters)
  monsters.each(&:attack)
end

monkey = IndustrialRaverMonkey.new
angel = DwarvenAngel.new

monsters = [monkey, angel]
call_attack(monsters)

We have two monsters each with a set of characteristics and an attack method, an instance of each of them is created, put into an array and finally they are given order to attack. The call_attack method is there in order to correctly replicate the Rust version, it is a bit redundant here.

The Rust version

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

trait Monster {
  fn attack(&self);
  fn new() -> Self;
}

#[allow(dead_code)]
struct IndustrialRaverMonkey {
  life: int,
  strength: int,
  charisma: int,
  weapon: int,
}

impl Monster for IndustrialRaverMonkey {
  fn attack(&self) {
    println!("The monkey deals {:d} of damage", self.strength)
  }

  fn new() -> IndustrialRaverMonkey {
    IndustrialRaverMonkey { life: 100, strength: 20, charisma: 10, weapon: 50 }
  }
}

#[allow(dead_code)]
struct DwarvenAngel {
  life: int,
  strength: int,
  charisma: int,
  weapon: int,
}

impl Monster for DwarvenAngel {
  fn attack(&self) {
    println!("The angel deals {:d} of damage", self.strength)
  }

  fn new() -> DwarvenAngel {
    DwarvenAngel { life: 100, strength: 50, charisma: 70, weapon: 50 }
  }
}

fn call_attack(monsters: &[&Monster]) {
  for monster in monsters.iter() {
    monster.attack();
  }
}

fn main() {
  let monkey:&IndustrialRaverMonkey = &Monster::new();
  let angel:&DwarvenAngel = &Monster::new();

  let monsters = [monkey as &Monster, angel as &Monster];

  call_attack(monsters);
}

The code is similar, but we have something called a trait, another thing called struct and yes, a main function. Let’s look a bit closer at each of the differences.

Comparing the implementations

The first and probably more obvious difference is that Ruby does not need an interface definition, called a trait in Rust, it relies on duck typing. What that means is that Ruby trusts you not to use a monsters that does not respond to attack. On the other hand, Rust’s compiler ensures that all the monsters have that function, throwing an error otherwise. Nothing to fancy here, it’s the dynamic versus strong typing duality you are probably already aware of.

Even though Rust relies strongly on types, it does have a very good ability to infer them, as you can see when the monsters variable is assigned on line 52.

Another thing you don’t have with Rust are classes, the way to get something close to a class is to have a struct, which defines a set of variables, a trait which defines a set of functions and mixing then with impl TraitX for StructY.

Still on the topic of traits, you might have noticed that one of the functions receives &self as a parameter and the other returns Self. Those are the equivalent to an instance method and initialize in Ruby.

The last difference I find worthy of note is that in Ruby most variables are pointers to the actual object and you have no control over that. In Rust you have three different types of pointers, owned, managed and borrowed. Having programmed in C a few years ago, I came to fear and respect pointers as the bringers of pain. Pointers in Rust are much nicer, mostly because of the language philosophy to put safety first, making it impossible for memory leaks and overflows to pass through the compile phase. It is also great with concurrency through a couple of constructs called tasks and channels.

It obvious that the Rust implementation has more code, but it also adds an extra layer of safety, which you might or might not want.

Good defaults

To be fair, Rust adds two “hidden” features. First, all variables are immutable by default and you have to make them explicitly mutable if you want.

1

let mut x = 1;

Secondly, all functions, structs and traits are private by default, so if I was to try and use them in another file:

1
2
3
4
5
6
7
8
9
10
11
12

#![feature(globs)]
use monsters::*;
mod monsters;

fn main() {
  let monkey:&IndustrialRaverMonkey = &Monster::new();
  let angel:&DwarvenAngel = &Monster::new();

  let monsters = [monkey as &Monster, angel as &Monster];

  call_attack(monsters);
}

I would get a bunch of compile time errors such as:

1

error: use of undeclared type name `IndustrialRaverMonkey`

Which just to prove the point can be fixed with:

1
2
3
4
5
6

pub struct IndustrialRaverMonkey {
  life: int,
  strength: int,
  charisma: int,
  weapon: int,
}

Conclusion

I have been fiddling with Rust for a very small amount of time, but I’m really liking how conceptually different it is from Ruby. It is a great language to learn some new ideas, and also to go down a level to where you have to use pointers.

Reloading Chrome

The first step is to be able to reload chrome from the command line, and you can get whichever script you want that achieves this goal.

I wrote one in bash and apple script.

1

osascript -e 'tell application "Google Chrome" to tell the active tab of its first window to reload'

Calling it from Vim

The next step is being able to call it from inside of vim, which can be done by writing a Vim Script function.

1
2
3
4
5

function! ReloadChrome()
  wall
  silent :!reload-chrome
  redraw!
endfunction

The call to redraw is not needed if you use gvim, but in terminal vim your screen will be all messed up unless you do it.

As a bonus you can also define a mapping to call this function easier.

1

nmap <Leader>rl :call ReloadChrome()<CR>

This is as far as Joe went, but I wanted to take it further.

FTPlugin

Vim has an awesome feature called are ftplugins or file type plugins, which are nothing but config files that are only loaded once you enter a buffer with a file of a specific type (type :h ftplugins in vim for more info).

I created one for html files, simply by creating a ~/.vim/ftplugin/html.vim file.

1
2
3
4
5
6

if exists("b:did_html_ftplugin")
  finish
endif
let b:did_html_ftplugin = 1

cabbrev <buffer> w <c-r>=(getcmdtype()==':' && getcmdpos()==1 ? 'call ReloadChrome()' : 'w')<CR>

This is just checking if the plugin is already loaded, and if it is not it defines a command mode abbreviation. In this case I’m redefining :w to :call ReloadChrome().

The getcmdtype()==':' && getcmdpos()==1 bit makes sure we don’t substitute any w that we type in a command, just if it the first letter.

A very important part of this code is the <buffer>, which ensures the abbreviation is only valid for the current buffer.

Now, every time we save an html file, the current tab on chrome will reload.

The extra mile

Since I spend a lot of time developing Rails apps, I thought I could go a step further and do something more clever than reloading the focused chrome tab.

For that I wrote a script that reloads a specific URL if there is an open tab with it, or opens a new tab.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

REGEX="^$1.*"

osascript &> /dev/null <<CODE
tell application "Google Chrome"
  activate

  if (count every window) = 0 then
    make new window
  end if

  set found to false
  set theTabIndex to -1
  repeat with theWindow in every window
    set theTabIndex to 0
    repeat with theTab in every tab of theWindow
      set theTabIndex to theTabIndex + 1
      if (do shell script "if [[ \"" & theTab's URL & "\" =~ $REGEX ]]; then echo \"found\"; fi") as text is equal to "found" then
        set found to true
        exit
      end if
    end repeat

    if found then
      exit repeat
    end if
  end repeat

  if found then
    tell theTab to reload
    set theWindow's active tab index to theTabIndex
    set index of theWindow to 1
  else
    tell window 1 to make new tab with properties {URL:"$1"}
  end if
end tell
CODE

Notice that I’m using a regex with the first variable of the script, so that it works for all paths of a domain, and it can be called from vim like this:

1
2
3
4
5

function! ReloadChromeRails()
  wall
  silent :!reload-chrome-url http://localhost:3000/
  redraw!
endfunction

And given that I use Slim as an html preprocessor, I can create an slim.vim ftplugin for this.

1
2
3
4
5
6

if exists("b:did_slim_ftplugin")
  finish
endif
let b:did_slim_ftplugin = 1

cabbrev <buffer> w <c-r>=(getcmdtype()==':' && getcmdpos()==1 ? 'call ReloadChromeRails()' : 'w')<CR>

And that’s it, everytime I save a view file, chrome reloads. All of this using (mostly) vim. Neat.

Pitfalls

For some reason my vim version was running html ftplugins for markdown files. You can check this by running :scriptnames which gives you a list of all the files that were loaded, and if there is something like vim/ftplugin/html.vim you have the same problem I had.

Look for a vim/7.4.253/share/vim/vim74/ftplugin/markdown.vim (or similar), open it and remove this line runtime! ftplugin/html.vim ftplugin/html_*.vim ftplugin/html/*.vim.

The Basics

This is very easy to do with capybara-webkit, you just need to add one line to your spec_helper:

1

Capybara.javascript_driver = :webkit

And a little magic flag on your RSpec example:

1
2
3

it "does something", js: true do
  ...
end

However, I have found myself in situations where, for a specific test, I want to use the selenium driver. The reasons can go from capybara-webkit not behaving like the real browser to, more commonly, me being on a debug mission and wanting to see it rendered on the browser.

Dynamic driver

To solve this problem I came up a solution that allows me to dynamically choose the driver I want for a given example.

I just added this snippet of code to my spec_helper:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

RSpec.configure do |config|
  config.before(:each) do
    Capybara.current_driver = select_driver
  end
end

def select_driver
  if example.metadata[:js]
    if example.metadata[:js] == :selenium
      :selenium
    else
      :webkit
    end
  else
    Capybara.default_driver
  end
end

This allows me to use the default syntax:

1
2
3

it "does something", js: true do
  ...
end

or to choose selenium:

1
2
3

it "does something", js: :selenium do
  ...
end

This is all fine and dandy, but I believe that in order to get closer to that utopic dream of the perfect system, more drastic and profound changes must happen. We need an architectural change, that shakes the foundations how we approach the writing and thought process of a rails application. To this, Uncle Bob has called the Clean Architecture.

The main igniters of this idea and therefore this article are a talk and an article by Uncle Bob Martin, but a lot has been written and spoken on the subject by a lot of different people and you can find the links I find more relevant on the bottom. They provide a good (mostly) theoretical overview of the problem and solutions, whereas this post aims at proving a very concrete solution with code samples in Ruby and Ruby on Rails, which is something I could not find anywhere.

The Basics

For those of you who don’t have the time to read the links, just want to brush off on some of the basic concepts or for the sake of us being able to communicate in the same vocabulary, let’s go ahead and define those concepts.

First off here’s a high level view of the clean architecture according to Uncle Bob:

As you can see there are different layers in the application, going inside out, the first two are the core of the app, where all the business rules and objects live. The other two are the “details”, the delivery mechanisms (in our case it will be Ruby on Rails), the databases (in our case postgresql), etc…

Entities

Entities are business objects, functions or data structures, that are responsible for all the non application specific business rules.

This means that if you have multiple applications that share the same domain (business) objects, the entities should not need to change in order to be usable by all of them.

Interactors or Use Cases

Interactors represent the layer for application specific business rules.

This is where most of the magic happens, they control the entire flow of the application, using entities, but never changing them.

They should not, however, be affected by changes to the UI, whichever they may be.

Boundaries or Adapters

A boundary is the interface that translates information from the outside into the format the application uses, as well as translating it back when the information is going out.

These boundaries may not be explicit, so much as they are logical or conceptual. In any case, they are there and you should be aware of it.

The Dependency Rule

This is the single most important concept, and you must always take it into consideration.

The dependency rule states that source code dependencies can only point inward.

There’s a generalization of the rule that applies to any application, source code dependencies can only point in one direction.

Applying it to the Real World™

By now you should at least know why such an architecture is important, and the main characters that come into play.

But, as I’ve said before, applying all of this into a real case scenario is what you probably don’t know and/or are curious about.

Our approach

We have to start somewhere, and we want to start on the right path, the best way I know how to do that is through a use-case & test driven approach.

I like this approach for two reasons:

1. We need tests to guide us and to provide confidence in the code base
2. Use-cases don’t let us stray from what brings value to the business

I’m not going to digress a lot into why TDD is awesome and you should do it, since there are a lot of resources out there on the subject. I will say that we’ll mostly be following Ian Cooper’s ideas on testing, for which the gist is the trigger for a new test should be a new use case, not a new class or method.

As for use cases, you can read Alistair Cockburn’s lovely book on the subject. But they should look something like this:

Notice that we have a main path and an alternative, which can also represent what to do in case of error. Also, there is no reference to anything related to the web, the use case level should be delivery mechanism agnostic. In other words, it must work the same way regardless of being used on the web, desktop or CLI.

The test

1
2
3
4
5
6
7
8
9
10
11
12

context "the company does not exist" do
  it "creates a member" do
    ...
    adder = Coworkers::CoworkerAdder.new
      params: params,
      space: default_space

    expect {
      adder.add
    }.to change{member_repo.all.size}.by(1)
  end
end

Now we have a test for the behaviour we expect, we just need to let it guide us.

Side note: This test was not written all at once, I followed the three rules of TDD to get here.

The interactor

The code to make this test pass (minus the private methods) is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

class CoworkerAdder
  def initialize(params: nil, space: nil)
    @member_repo = Repository.for(:member)
    @company_repo = Repository.for(:company)
    @params = params
    @space = space
    @member = Member.new member_params
  end

  def add
    if member.valid?
      member.company_id = company.id
      member.space_id = space.id
      member_repo.save(member).value
    end
  end
...

The Interactor - step by step

There are a lot of interesting bits of code in our interactor, and a lot of decisions that were made. Let’s take a closer look at each of them.

Repositories (Gateways)

In order to abstract the persistence mechanism I decided to use the Repository Pattern, in which we have repositories for each type of persistence mechanism we want to use and that can be used interchangeably.

Sounds a lot like an interface? Well, it is, kind of… In Ruby we don’t have interfaces, we just go ahead an use what we call a duck type.

Here’s an example of an in memory repository:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

module Repositories
  module Members
    class Memory
      def initialize
        @members = {}
        @next_id = 1
      end

      def save(member)
        member.id = @next_id
        @members[@next_id] = member
        @next_id += 1
        member
      end

      def all
        members
      end

      def first
        first_key = members.keys.sort.first
        members[first_key]
      end

      def last
        last_key = members.keys.sort.last
        members[last_key]
      end

      private
      attr_reader :members
    end
  end
end

What’s really relevant here is the object’s public API, it’s interface, the save(member), all, first and last methods, since they’re what defines a valid repository for a member.

The Repo Boss

Someone, somewhere needs to know which repository to use for each entity or use case (repositories do not need to exists in a 1-1 relation with entities, even though most of the time they do). That someone is a very simple class I call Repository, which tracks the registration of repositories:

1
2
3
4
5
6
7
8
9
10
11
12
13

class Repository
  def self.register(type, repo)
    repositories[type] = repo
  end

  def self.for(type)
    repositories[type]
  end

  def self.repositories
    @_repos ||= {}
  end
end

As you might have guessed, we then need to register the repositories we want. That is very simple and very easy to hide behind some sort of configuration, but here’s how it’s done:

1
2
3
4
5
6
7

require 'repository'
require 'repositories/members/memory'
require 'repositories/companies/memory'

Repository.register :company, Repositories::Companies::Memory.new

Repository.register :member, Repositories::Members::Memory.new

After all this setup is complete, you can access repositories the way it is shown in lines 3 and 4 of the interactor.

Member Entity

Entities should have a bunch of attributes and some methods that operate on them, that enforce non app specific business rules.

A simple approach to it could be this:

1
2
3
4
5
6
7
8
9
10
11

class Member
  attr_accessor :id, :company_id, :name, :email,
                :phone_no, :boss, :observations,
                :space_id, :created_at, :updated_at

  def initialize(attrs = {})
    attrs.each do |attr_name, attr_value|
      public_send("#{attr_name}=", attr_value)
    end
  end
...

There might be ways of doing this that are more elegant or clever, you could, for instance, extract common attributes such as id, created_at and updated_at (or you could not even store them here, if you feel they are to “railsy”). For now this approach will suffice, though.

Validations

On line 10 of the interactor you can see the method valid? being called on the member entity. The easiest way I could think of to implement validations was this:

1
2
3
4
5
6
7
8
9
10

def valid?
  name && email
end

def errors
  error_messages = []
  error_messages << "missing name" unless name
  error_messages << "missing email" unless email
  ValidationErrors.new(error_messages)
end

That needs a tiny wrapper to be rails compliant, to which I called ValidationErrors.

1
2
3
4
5
6
7
8
9
10
11
12
13

class ValidationErrors
  def initialize(error_messages = [])
    @error_messages = error_messages
  end

  def full_messages
    @error_messages
  end

  def size
    @error_messages.size
  end
end

If you have no problems with including ActiveModel, you can add it as a gem and do simply this:

1
2
3
4
5

class Member
  include ActiveModel::Validations

  validates_presence_of :name, :email
end

As with any good engineering problem, there is no correct answer. There are trade offs in both solutions, one may take longer to implement, but is small, the other has everything you need and probably a bunch of other stuff as well. Pick your poison.

Database dependent validations

What about validations that depend on the database, such as validating uniqueness, you might ask. The easier way would be to add that validation on the repository, but that would spread business rules for an entity across multiple files and we don’t want that.

The solution we came up with is to have a generic unique? method on the repository and calling in from the entity:

1
2
3
4

def valid?
  super &&
  repo.unique?(self, :name)
end

The implementation of the unique? method for the in memory repository is as follows:

1
2
3
4
5
6

def unique?(object, attr_name)
  @members.values.none? do |member|
    object.id != member.id &&
      member.public_send(attr_name) == object.public_send(attr_name)
  end
end

Crossing Boundaries

A very important part of this whole architecture is crossing layer boundaries, especially the boundary that separates the application from the delivery mechanism. You want to make sure not to pass entities around, since they come with a bunch of business rules attached, instead you should pass value objects, or plain data structures.

I prefer to pass data structures, but have the serialization from entity to data abstracted on a method called value, which allows for the interactor to do what it is doing on line 14:

1

member_repo.save(member).value

What does that value do, you might ask. It simply calls a serializer.

Serializers

The value of an entity can be defined as follows:

1
2
3

def value
  Serializers::Raw.new(self).serialize
end

It takes an object (in this case an entity), and serializes it’s attributes, which, by default, it assumes come from an attributes method. The serialize method can handle both an hash with all the attributes, in which case it just returns it, or an array with just their names, from where it can create the hash with the names pointing to the values.

1
2
3
4

def serialize(attrs_method: :attributes)
  attributes = object.public_send(attrs_method)
  get_real_attributes_from attributes
end

ActiveRecord Repository

We’ve already talked about repositories and that they are duck types for a gateway’s logical interface, you even saw an implementation in memory. But since a very common pattern is to use Rails with ActiveRecord, I feel like I should show how an AR implementation looks like.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

require 'active_record'

module Repositories
  module Members
    class ActiveRecord
      ...

      def last
        ::Member.new(Member.last.value)
      end

      class Member < ::ActiveRecord::Base
        def value
          Serializers::Raw.new(self).serialize
        end
      end
    end
  end
end

There are a few things of note here. One of the most obvious is that we define the “model”, i.e. the class that inherits from AR::Base, as an inner class of the repository. We do this because we don’t (and shouldn’t) need to use it anywhere else, in fact, all references to AR should be encapsulated by the AR repository.

This leads us to the next thing of note, the fact that we do not return nor an AR object, nor an AR relation. The interactor (which will be calling this) only knows how to deal with entities, so we get the value from the AR object, using a serializer, and wrap it in an entity. All references to AR are gone.

Connecting with Rails

Now we have a working application (hopefully), we just need a way to deliver it to our clients. We can do that using a CLI, web app, desktop app, REST API, or any other way we so choose. As an example I chose to deliver it as a Rails app.

There are basically two steps in making this work with a Rails app:

1. Deploy our core application as a gem
2. Require, configure and use it from the rails app

The gem

I’ll not get into details on how to create gem, as that goes way beyond the scope of this article which is already extensive, there are just a few “tips” to make it easier to use.

A good way to make your gem painless to use is to autoload most of the stuff when it is required. So your main file should look somewhat like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

require "cohive/core/version"


autoload :Repository, "repository"

module Coworkers
  autoload :Company, "cohive/core/coworkers/entities/company"
  autoload :Member, "cohive/core/coworkers/entities/member"

  autoload :CoworkerAdder,
    "cohive/core/coworkers/interactors/coworker_adder"
end

module Serializers
  autoload :Raw, "serializers/raw"
end

Another must have for a gem is to be configurable, I do it like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

module Cohive
  module Core
    def self.configure
      @repository_config = RepositoryConfig.new
      yield self
      post_config
    end

    def self.repository=(repo_type)
      @repository_config.default_repo_type = repo_type
    end

    def self.repository
      @repository_config
    end

    def self.post_config
      @repository_config.load_repos
    end
  end
end

With this configuration options I allow the delivery mechanism to choose which repository to use for each of the repositories that are available.

The Rails app

Using the gem in the Rails app is even simpler, you just include it on the Gemfile:

1

gem 'cohive-core', path: "../cohive-core", require: false

Require and configure it:

1
2
3
4

require 'cohive/core'
Cohive::Core.configure do |config|
  config.repository = :active_record
end

And finally, use it:

1
2
3
4
5
6
7

def create
  adder = Coworkers::CoworkerAdder.new params: member_params,
                                       space: current_space
  if adder.add
    flash[:notice] = t('coworkers.member.flash.added_success')
  ...
end

As simple as that.

Conclusion

I truly believe this is a great way to build applications, and even though some of my solutions might have room for improvement, the overall architecture and underlying ideas are very mature and should definitely be taken into consideration.

Here’s a recap of the main ideas covered in this article:

• The application should not depend on the delivery mechanism or database, those are details
• The application’s functionality should be driven by use cases
• The application’s design should be driven by tests

Everything that follows is a consequence of this.

A nice side effect of using this architecture is that there is no need to load entire frameworks such as rails, or using a real database to run your unit tests (you might want to do integration and system tests, but that’s for another day) which means they are fast.

Here’s the tests for the service that does the same as the interactor, but from the rails app:

Notice that it takes 3.96s to run the tests. Now for the interactor with the clean architecture:

Notice that I’ve added more tests and yet it takes only 0.54s to run them all. It’s an 86.4% improvement in testing time! When doing TDD you should be running your test every 30s or so, that’s a gain of approximately 54 minutes per work day.

Relevant Links

• Architecture, Use Cases and High Level Design by Uncle Bob Martin
• Boudaries by Gary Bernhardt
• Clean Coders Discussion Board
• Ports and Adapters by Alistair Cockburn
• Hexagonal Architecture for Rails Developers by Victor Savkin
• Hexagonal Rails by Matt Wynne

diff -u <(curl http://example.com/xpto) <(curl localhost:3000/xpto)

It’s not that it’s hard to write tests, but they’re hard to get right. It all starts with a little bit of tight coupling and a mock or two in the wrong place, but it quickly scales to a huge and brittle test suite.

At this point your tests fail with every little change to the code base, they take forever to run and the whole development team feels bad about them, blaming them for every problem.

The first time you try to add TDD to your team’s process it is very easy to dig yourself into this kind of hole, where your test suite adds no confidence, design feedback nor team velocity. This will usually happen due to a lack of understanding of the TDD philosophy and lack of experience writing tests. Believe me, I’ve been there.

The worst thing you can do when facing such a situation is to blame it on TDD and discard it completely. It is great and it definitely works, but if you have no experience with it, you might want to ease your way into it.

So, let’s break TDD down into three major goals

1. Confidence in your system
2. Design feedback
3. Team velocity

The first we’ll try to get is confidence, then feedback and velocity will hopefully take care of itself. In order to do that, I came up with this chart:

The top left quadrant is the simplest to implement on a team, you do high level acceptance or integration tests on the critical paths of your app, after the features are written. The goal is that if any of these tests fails, you’re app is not usable. This is a good way to start adding tests to an existing code base.

The bottom left quadrant builds on top of the first, but adds confidence by adding some unit tests to critical algorithms in your app. The confidence you gain is that if a big feature fails, you have a finer grained knowledge of where the error might come from.

On the top right quadrant we start writing tests first, which will (if done correctly) provide bigger design feedback and ultimately generate an overall better code base. However, this is the time it starts to get harder, so your team will really have to be on board with this, or else it just won’t work.

On the bottom right quadrant we are writing both acceptance/integration and unit tests for the critical paths of our app before the code that makes them pass (one test at the time, obviously), we are on a good way to having TDD at it’s finest.

After you’ve nailed all of these quadrants, it’s time to go full blown TDD.

Takeaways

One thing to keep in mind though is that there is no silver bullet and this is not a religion.

TDD works great in a lot of situations, but it may not be fit for others, just give it a fair chance and weight the pros and cons on each situation. If after that you feel TDD is slowing you down, consider dropping it.

The parser example would be something like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

require 'observer'

class DB
  def initialize(consumer)
    consumer.add_observer(self)
  end

  def update(data)
    self.store(data)
  end

  ...
end

class Consumer
  include Observable
  attr_accessor :parser

  def initialize(parser: XMLParser)
    @parser = parser
  end

  def consume(data)
    parsed_data = parser.parse(data)
    changed
    notify_observers(parsed_data)
  end
end

Here the database is observing the consumer, and when it has any new parsed data, the DB gets notified and acts accordingly. If there is no database, the consumer goes on with it’s business and nothing else happens, but there can be one, two or more databases, loggers, etc, listening and performing actions when the data is parsed.

Observer is a library that comes bundled with ruby, but there are others you can use, such as:

• wisper-async
• publisher

Rails had it’s own observers you could use, they were removed from the core in version 4.0, but you can still use them as a gem.

• rails-observers

The observer pattern is to a certain extent similar to javascript’s events and as them, it can make your code really hard to understand and even debug, but used at the correct time and place is a very powerful tool. Use it wisely.

1
2
3
4
5
6

class Consumer
  def consume(data)
    parsed_data = XMLParser.parse(data)
    DB.store(parsed_data)
  end
end

There is (at least) one big problem with this approach, and it will manifest itself when you want to support another data format, such as JSON. The Consumer class is tightly coupled with the XMLParser, and therefore it’s hard to add other parsers, so we need to decouple them. We’re going to do that using a technique called Dependency Injection, like so:

1
2
3
4
5
6
7
8
9
10
11
12

class Consumer
  attr_accessor :parser

  def initialize(parser: XMLParser)
    @parser = parser
  end

  def consume(data)
    parsed_data = parser.parse(data)
    DB.store(parsed_data)
  end
end

This way we can inject the parser on initialization, or even after that. Note that we have a default which is the XMLParser, but it is not mandatory to have a default value.

So, after the refactoring, adding a JSONParser is easy.

1
2

consumer = Consumer.new(parser: JSONParser)
consumer.consume(data)

This technique can be used in many scenarios, in this example we used it as part of a pattern that’s called strategy pattern.

Special Thanks

I would like to thank Gonçalo Silva for the help with the examples and also Zach Holman for the inspiration for the talk design from his awesome blog post called Slide Design for Developers and for the talk that inpired it.

You can check more of his talks here, if you ever need inspiration.

Resources

There are a bunch of links to resources on this topic in one of the last slides.

You can also check the code samples from the talk on github.

Special Thanks

I would like to thank Zach Holman for the inspiration for the talk design from his awesome blog post called Slide Design for Developers and for the talk that inpired it.

You can check more of his talks here, if you ever need inspiration.

If you know me well enough you’ll know that I hate documentation, which seems rather contradictory, but I think it all boils down to what good documentation means.

Good documentation, in my opinion, are not wikis, a bunch of shared documents, progress reports, etc… That’s management crap. All a development team needs is a commit history with good commit messages.

Note: I’m using git and git nomenclature as an example, but this applies to any versioning system.

Commit Message Example

Here’s an example of what I consider a good enough commit message. It is composed of three parts:

1. A first line of no more than 80 characters that sums up the purpose of the commit
2. One or two paragraphs to explain the changes from a user point of view (user story if available)
3. A bullet list of technical modifications of note

Integration into the flow

If you follow a flow that’s similar to mine, you don’t need to worry about writing this messages in every commit, since that would be tedious.

What I do is, when on a topic/feature branch I commit at will, with any message I see fit at the moment. This well written message comes only when creating a pull-request, so that someone doing a code review can better understand the changes.

Conclusion

This way of doing commits, in my opinion, make it really nice to read through the git log of summaries, and when in doubt of what a commit does, it’s easy to get more info, providing a nice way of developing as a team. Although it’s also a reminder of why something was done that way, for when you’re looking at the code some time later.

The analogy is not that absurd, as matter of fact it is not absurd at all in my opinion, as tests are the core of any application, especially one for the web. Without tests an application won’t live long, it will probably be able to stay alive for a while, but at the first need for change or growth, it will fester and die. As a developer I much prefer not being around when such things happen, and most of all I believe it is my duty to impede this from happening, it’s the developer’s code of honour, it’s the reason I call myself a professional developer.

As you can see I do have a very strong opinion on this subject, and I really am suggesting that if your writing a web application without tests (preferably TDD but not necessarily) you’re not only doing it wrong, but you’re being unprofessional and utterly irresponsible. Plainly put, you should not be writing code!

A little side note here to all of those starting in this business or that just now have been introduced to testing, this article should be a good starting point on your quest to a brighter future where tests lead the way. Moreover, you should not include yourself in the group of irresponsible developers out there, if you actually start testing, obviously. Testing is something that is rarely introduced in CS majors and most starting developers don’t get to have an older and more experienced mentor to teach them this stuff, so it’s really not your fault and you have all my respect and appreciation for trying to learn this. Also, not everyone has to be a professional developer, and that’s fine. Just don’t try to impersonate one, that’s all I’m asking.

Now that we’re done with the contextualization let’s get to the juicy part of the article, where I’ll introduce some basic concepts and keywords of testing (some of which you might have already heard of) and slowly progress into more advanced and “philosophical” ones.

The religions

TDD, BDD and traditional testing. This are the most adopted religions in the testing community.

You’ll often see them referred to as methodologies, processes or even philosophies, but I believe they’re more than that. As a developer this will drive not only your code but also the way you think and solve problems. It’s a way of life, so choose carefully and embrace it (well, maybe I’m being a bit dramatic here, you can change your mind afterwards, trying to mix them too much is ill advised, though).

TDD

Test driven development, as the name states, is when you let your tests drive your application’s code. It is often coupled with an agile software development process, as it too work in very short cycles composed of three phases:

1. Red - You make a test for a feature you wish you had (usually it will test a very specific part of that feature)
2. Green - You write only enough code to make the test pass, not more, not less (at this point you should commit your work)
3. Refactor - You are now in a green field, where you have a solution that may not be optimal but it works and a test to make sure that it ever stops working you’ll know about it. This is the perfect time to think of a better way of solving the problem

This is the core of TDD, it states that if you repeat this cycle over and over again you’ll have smaller and more focused classes, looser coupling and cleaner interfaces.

There is, AFAIK, no real proof of this, but TDD does provide you a great test suite, which combined with a control version system gives you much more confidence in your code, as well as more freedom to change things and an easier way to debug regressions also, (and some might argue this is the greatest benefit of TDD) if done right, you get documentation for free.

TDD can actually be divided into two subgroups, according to Martin Fowler, the classical and the mockists, but we’ll get to that later on.

Right about now you should be wondering, “if TDD is so great, why even bother having other ways of testing?”. It turns out that TDD is not perfect, mostly due to our own faults as developers, such as the tests failing to cover an important edge case or the tests being badly written leaving us a bigger code base to maintain. Another problem might be that we as overzealous as we are, try to test every possible scenario for every little bit of code, this is counter productive and to know what and how much to test is a kind of art that will come with experience (we’ll cover some ground rules that make this an easier task, though).

When doing TDD (or any kind of tests) there is one thing you should be constantly aware of, “your code is NOT bug free!”. Rest assured, bugs will appear, but they will probably not be on your main flow of things, and when they’re fixed, they’ll stay fixed.

Uncle Bob Martin describes TDD in three basic rules/laws:

1. You are not allowed to write any production code unless it is to make a failing unit test pass.
2. You are not allowed to write any more of a unit test than is sufficient to fail; and compilation failures are failures.
3. You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

One of, if not the most important thing in TDD is that you write your own tests. I like to go a bit further and say that the tests are part of the code.

BDD

Behaviour Driven Development is largely based on TDD, it differs mainly in the fact that it focus in the behaviour of things instead of how they work, which is why BDD always starts by defining a scenario. Plainly put, you focus primarily on the user interaction and the user’s point of view.

For instance, imagine you would like to implement and ATM, with TDD you would probably start by testing if the withdrawal and card validation mechanisms, whereas with BDD you would write a scenario such as this:

1
2
3
4
5
6
7

Given the account is in credit
And the card is valid
And the dispenser contains cash
When the customer requests cash
Then ensure the account is debited
And ensure cash is dispensed
And ensure the card is returned

Almost everything else in TDD will also apply here, but this small change in perspective will have a deep impact in the resulting solution.

This type of scenarios have some rules, though, they have a special syntax so that they can be understood by the non-technical people of the team or company, but also so that they can be automated. As a matter of fact, doing this you have not only a test suite, but also a pretty good documentation and feature specification.

When writing scenarios I tend to prefer to write them declarative as opposed to imperative, as I feel that otherwise it would pretty much defeat the whole purpose of writing them. Here’s a pretty good take on the differences

If you ever tried TDD you probably have faced the “what do I test first” situation, BDD sets to solve that as you always start with the scenario and let it drive you. In the example above you would first write a failing test that would check that the account has credit, and then make pass, then you would write a failing test for the card validation and make it pass, and so on. Bare in mind though that making these tests pass may require going to different layers of the application and further testing, but you’ll always know what to test first.

BDD is more elegantly described by it’s creator Dan North from whom I took the ATM example in this article.

Traditional Testing

I call this traditional testing for the lack of a better term, but this is the model you’ll see in companies that adopt very strict development methodologies such as waterfall or RUP, and it happens when there is an entire team whose only purpose in life is to do write tests.

In this model the tests start to be written after the development is complete, IMHO it some serious drawbacks (even though I’ve never personally used it, I must admit):

1. The tests and it’s expectations don’t drive the code and the probability of having poorly written, extremely coupled code is much higher
2. Management is always pushing for deliverables and/or deploys, in the event of delays the test phase will be the first to suffer the consequences

Even if the test process starts in sync with development process it is harder and less productive to have someone else write the tests for your code as you’re writing it.

In case you haven’t yet figured out, I’m nor a big fan, nor a big connoisseur of this type of testing, still I did not want to go by without mentioning the ways of the past.

Going a bit further into TDD

The main focus of the rest of this article is going to be TDD with Rails, but as I’ve said earlier TDD has two subgroups, from which I’ll choose one (not 100%, but almost) and even borrow a few high level concepts from BDD.

Classical TDD

When writing tests, classical TDDers will not use mocks and use stubs as little as possible, mostly to fake web services and the such. They focus entirely on the final state of the system, in the ATM example, they would test that the machine has given money to the user, for example.

In this approach the tests for an object will test it’s functionality as well as it’s neighbours’.

Mockist TDD

Mockist TDDers will use mocks to filters everything that is not the SUT (System Under Test). Taking the ATM example one more time and imagining the SUT is the card validator, they would test that if the card is valid, the give_money_to_user method was called on the money dispenser. The focus here is on behaviour instead of state.

In this approach the tests for an object will test it’s functionality as well as it’s communication with it’s neighbours.

Check out Martin Fowler’s article on this for a much more in depth analysis of the difference between classical and mockists TDDers, as well as the difference between mocks and stubs.

Outside-in testing

Outside-in testing is a process that goes pretty much hand in hand with BDD in terms of where it begins. When doing this we start by writing an integration or acceptance test (this could be a BDD scenario), and go from there.

The main purpose here is to let the code be driven by the feature the clients actually want, so you don’t start coding away before having a good grasp on how the user experience is going to be.

This process plays well with both BDD and TDD, it’s really up to you which religion to live by. I tend to prefer the mockist TDD approach, which is kind of a hybrid, and I’ll explain in full detail how to do it in a Rails app.

For a thorough example of outside-in testing, please refer to Harold Gimenez article.

Middle-out testing

Another way of doing tests would be to start by the core classes of your system, and work your way to the layers, such as UI and database. In Rails this would translate to first write tests and respective code for the most important models and controllers, and they work your way to migration, validations, etc, as well as the views.

I’ve taken this approach several times and discourage you from doing so, because this will probably lead to adding too much features to your system, and make the final system to not accurately represent the clients wishes.

Final Notes

I believe we covered a lot of ground here, there is however, a lot more you can do to become a more proficient tester and therefore a better developer.

In my opinion you should really focus on two things if you indeed intend to improve your code’s quality through testing, write and read, simple as that.

You should definitely write a lot of tests so you can face the problems, and have your own doubts. That’s how you learn any programming language, principle or methodology, by hitting your head on the wall until you realize there’s a door right beside you.

You should also read a lot, so that that door becomes easier to find and open. Throughout the article I’ve provide some links you should really go ahead and read if you haven’t done so already, but I’ll leave some more extensive reading material (and some screencasts) I recommend.

• Clean Code
• Clean Coders
• Test-Driven Rails
• The Rspec Book
• Beginning Outside-In Rails Development with Cucumber and RSpec
• Test Driven Development: By Example
• RSpec 2: The Basics
• RSpec 2: Tools

Now go and TDD away. And most of all try to have fun doing it (pairing is a nice way of achieving this).

This is easy enough to do by stubbing out the calls to model or ActiveRecord code. On a real application though, you’ll usually have to authenticate users and/or do some kind of authorization. This too should not have to go through the database.

For authentication I’m using Devise and for authorization CanCan, and setting up a controller test on RSpec goes somewhat like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

def controller_full_setup
  setup_devise
  setup_ability
  setup_host
end

def setup_ability
  @ability = Object.new
  @ability.extend(CanCan::Ability)
  @controller.stub(:current_ability).and_return(@ability)
end

def setup_host
  @request.host = 'test.example.com'
  default_url_options[:host] = @request.host
end

def setup_devise
  @request.env["devise.mapping"] = Devise.mappings[:user]
end

1
2
3
4
5
6

it "does something" do
  controller_full_setup
  @ability.can :do, :action

  # rest of the test
end

With this setup you are logged in to devise as a user, and have a blank cancan ability object in which you can define the abilities needed for the purpose of the test.

It’s a pretty simple plugin that stores each callback you had on DOM ready and runs it on page:change, the turbolinks event.

So, you might think all your problems are solved, but it is not quite so. What if you want to run some code just for a specific page? Or include a file for a specific page?

Using turbolinks render the usage of stuff like content_for :head impossible, as the head will already be on cache, and the code you added to it will not run.

And if you try to add the code in the body, jquery.turbolinks will add the callback each time you go to the page, which means that if you visit the same page twice before a full page refresh, your code will also run twice. Not very good…

Rails 3.1 asset pipeline

The asset pipeline has three goals, precompile, concatenate and minify.

So, even though the rails generators create a .coffee file for each controller, the normal usage would be to have all of them concatenated into one, when in production. This file will be loaded on the home page and can be cached the rest of the way.

There are obviously some times when we might want to add some files in other places than the home page. For that we’ll have to create a new manifest files and explicitly tell rails to add it to the precompile path. A common usage for this is to have a footer.js manifest for files that are loaded after the rest of the body.

If we want to add such manifests to the body, using turbolinks and jquery.turbolinks, we’ll have the same problems if the code is actually trying to run code, and not just defining functions and variables.

The pipeline trap

A problem with having all you’re files concatenated is that you have to be extra careful with when and where you attach event listeners. For instance, if you attach an event to an li in the posts.coffee file, and it is then included in the application.js manifest, all the li’s in your application will have that listener.

There are two ways (that I know of) of solving this problem.

You can either add a class or id to the body element of each page, such as posts_index and then attach the listeners to the li’s only when the body has that attribute.

1
2
3

$ ->
  if $('body.controller_name_action_name').length > 0
    // Do some stuff here

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<!DOCTYPE html>
<html>
<head>
  <title>AppName</title>
  <%= stylesheet_link_tag    "application" %>
  <%= javascript_include_tag "application" %>
  <%= csrf_meta_tags %>
</head>
<body class="<%= "#{params[:controller]}_#{params[:action]}" %>">

<%= yield %>

</body>
</html>

Or you can encapsulate all your code into functions, and then make them visible in the page you want to call them on.

1
2
3
4
5
6

$ ->
  random_function = ->
    console.log "Hello World"

  window.exports ||= {}
  window.exports.another_random_name = random_function

You need to export the functions because coffeescript will not let functions and variables defined in a file pollute the global scope, and the easiest way to do it a browser is to attach them to the window object which is always present. We add an exports namespace so that the window namespace will not be polluted with all our functions, but it would work even without it.

I tend to prefer the second approach for two reasons. First, and even though it adds JavaScript to the body, it is less obtrusive. And second, because it integrates with turbolinks, as it does not assume the code in the head is run every time.

The Turbolinks Problem

We still have a problem, though. Code that’s in the body running more than once.

The easier way I found of solve this was to use the once function from the underscore library. Obviously I was already using underscore for other stuff, or else it would be a complete overkill. If you just need this one function, define it somewhere that gets concatenated into your application.js file.

So, calling the function I defined above would look like this:

1
2
3
4
5

<script>
  jQuery(_.once(function($){
    window.exports.another_random_name();
  }));
</script>

And if you want to use the once function, give credit to Jeremy Ashkenas, Brad Dunbar and many others, and go ahead and copy paste.

1
2
3
4
5
6
7
8
9
10

_.once = function(func) {
  var ran = false, memo;
  return function() {
    if (ran) return memo;
    ran = true;
    memo = func.apply(this, arguments);
    func = null;
    return memo;
  };
};

Resources

• Principles of OOD
• Decompose fat Active Record models
• Ruby Science
• Clean Code
• Design Patterns in Ruby
• Rails Anti Patterns
• Thoughbot’s blog
• Refactoring from Good to Great by Ben Orenstein

Special Thanks

I would like to thank Zach Holman for the inspiration for the talk design from his awesome blog post called Slide Design for Developers and for the talk that inpired it.

You can check more of his talks here, if you ever need inspiration.

Don’t fret if you haven’t, I’ll break it down for you. Imagine you have a Post model which may have one or more Comment, and that in your view you do something of the sort (assuming @posts = Post.all):

1
2
3
4
5
6
7
8
9
10
11
12
13

...
<% @posts.each do |post| %>
  <article>
    <p><%= post.body %></p>

    <footer>
      <% post.comments.each do |comment|
        <p><%= comment.body %></p>
      <% end %>
    </footer>
  </article>
<% end %>
...

In this snippet, a query for fetching the comments is being performed for each post, so it’s N for N equal to the number of posts plus 1 queries to list the posts. For a big number of posts you’ll swamp your database.

In order to prevent this you can do @posts = Post.includes(:comments).all that will eager load all the comments of all the posts and store them in memory, so when you try to access them you don’t hit the database.

Nested Eager Loading

A feature that I find rather undocumented is that it is possible to eager load a relation of an object you’re eager loading, such as the author of a comment if you wanted to access it’s name or avatar, for example.

That can be achieved by passing an Hash as an argument to the includes method instead of a Symbol, for the example above it would be, @posts = Post.includes(comments: :author).all.

I have tried it to three levels of nesting which is already more than you should ever need, still it can go deeper than that, not sure how much deeper, though.

Better Errors

This was covered in great depth by Ryan Bates in a RailsCasts #402. After you install the gem, when you get an application error instead of this:

You’ll be prompted with something like this:

Note that by adding binding_of_caller gem you’ll also have a REPL on the point of failure.

Pry

Better errors with a REPL is going to take care of most of your problems when doing a full stack request, but if you are developing some model classes or even some libraries in Rails or plain old Ruby, you may want to declare breakpoints so you can do some debugging.

Debbuging with pry is as easy as droping the binding.pry line wherever you want the breakpoint, like so:

1
2
3
4
5
6

class PostsController < ApplicationController
 def index
   @posts = Post.all
   binding.pry
 end
end

When running this code, your server will stop at the breakpoint and you should see this:

This has been covered on RailsCasts #280. One thing Ryan doesn’t mention though is the pry-rails gem, which will sub in as your rails console and give you some nicities as showing routes and the schema for a given model in a good looking way.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

$ rails console
[1] pry(main)> show-routes
     pokemon POST   /pokemon(.:format)      pokemons#create
 new_pokemon GET    /pokemon/new(.:format)  pokemons#new
edit_pokemon GET    /pokemon/edit(.:format) pokemons#edit
             GET    /pokemon(.:format)      pokemons#show
             PUT    /pokemon(.:format)      pokemons#update
             DELETE /pokemon(.:format)      pokemons#destroy
        beer POST   /beer(.:format)         beers#create
    new_beer GET    /beer/new(.:format)     beers#new
   edit_beer GET    /beer/edit(.:format)    beers#edit
             GET    /beer(.:format)         beers#show
             PUT    /beer(.:format)         beers#update
             DELETE /beer(.:format)         beers#destroy
[2] pry(main)> show-routes --grep beer
        beer POST   /beer(.:format)         beers#create
    new_beer GET    /beer/new(.:format)     beers#new
   edit_beer GET    /beer/edit(.:format)    beers#edit
             GET    /beer(.:format)         beers#show
             PUT    /beer(.:format)         beers#update
             DELETE /beer(.:format)         beers#destroy
[3] pry(main)> show-routes --grep new
 new_pokemon GET    /pokemon/new(.:format)  pokemons#new
    new_beer GET    /beer/new(.:format)     beers#new
[4] pry(main)> show-models
Beer
  id: integer
  name: string
  type: string
  rating: integer
  ibu: integer
  abv: integer
  created_at: datetime
  updated_at: datetime
  belongs_to hacker
Hacker
  id: integer
  social_ability: integer
  created_at: datetime
  updated_at: datetime
  has_many pokemons
  has_many beers
Pokemon
  id: integer
  name: string
  caught: binary
  species: string
  abilities: string
  created_at: datetime
  updated_at: datetime
  belongs_to hacker
  has_many beers through hacker

$ DISABLE_PRY_RAILS=1 rails console
irb(main):001:0>