The stupidest thing I ever saw a developer do

So this story comes up quite a lot – this is the stupidest thing I ever saw a developer do. I need to paraphrase a little because it’s been many years, but in a nutshell we’d had a new guy start as a junior developer and he was working through bug tickets, with instruction to run solutions past another developer prior to checking them in. He was dealing with an issue where the backtrace read something like this:

undefined method `capitalize' for nil:NilClass (NoMethodError)

Which is a relatively simple exception to explain and is probably, in my experience, the most common backtrace a developer will ever see. It usually means that someone has not coded defensively, or that something has been coupled to something else in a non-obvious way and someone didn’t realise. You can easily achieve the error yourself:

my_hash = {}
my_hash[:key].capitalize

Anyway, after working on it for a few hours our developer came to me with his solution. Here is what he had done:

class NilClass
  def method_missing(method_sym, *arguments, &block)
    return
  end
end

For non-rubyists, here is a translation of what that bit of code does:

Let’s change the meaning of nothing, so that whenever someone tries to do something to nothing, we just do nothing.

I am not entirely proud of my reaction at the time, which was basically to laugh at the guy, tell pretty much everyone in the office about what he’d done, and then continue to tell the story for many years to come. To his credit, this “fix” had actually, to the untrained eye, fixed the problem because the software was now behaving as expected.

Evidently, the developer in question had, upon seeing the backtrace, Googled it. He had found a stackoverflow entry where someone else was having the same issue and some helpful user had submitted the NilClass monkey patch as a joke answer to the question. Other helpful users had up-voted this answer, which lead to our guy not identifying it as a joke.

I tried in vain to track down a link to this stackoverflow entry (it was many years ago) but to no avail.

Like I said, I tell this story quite a lot – the most recent time was earlier on today in fact, and it got me thinking. I worked through  the steps that this particular developer had taken:

  • He googled the error
  • He found a “solution”
  • Without understanding it, he stuck it in the codebase

And it dawned upon me that maybe I had been a little harsh on the guy, because that little trio of bullet points right there is one I have followed a whole bunch of times myself, especially when I was first getting started as a dev.

I never had a mentor, and regularly found myself being completely out of my depth and being asked to do things which I had no idea how to do. It was scary, it was stressful, and whilst being pushed in the deep end does make you very good very quickly (provided you swim) it can lead to you becoming overly reliant on the internet for solutions. You become adept at “skimming over documentation”. It’s bad practice.

If this story feels kind of familiar to you, then know that you are not alone – almost every programmer I have ever worked with has at some point engaged in “stackoverflow driven development” . Nowadays I always try to be aware of what I do not know – Taking time to properly understand what a solution means is not wasted time.

And if the guy who I laughed at ever reads this, please consider this an apology.

Ruby’s instance_exec method

instance_exec is a method you can use to change the “scope” of a block. One of the great advantages of doing this is that it can make your code more readable, particularly when writing a Domain Specific Language (DSL). So how does instance_exec work and why would you ever want to write a DSL?

instance_exec is pretty easy to demonstrate by way of a silly example. Let’s suppose you are running a Cattery. For anyone who doesn’t like silly examples, you can think of the cats as some kind of unmanaged resource (for example, a database connection) and the cattery as a pool of these resources (e.g. a database connection pool). Any cats that manage to escape the cattery can be considered to therefore be a memory leak that will harm your application and ultimately lead to sleepless nights and long days.

It might actually be easier on stress levels to just think of them as cats.

First, we define a simple class to represent a “cat”:

class Cat
  def speak!
    puts "meow!"
  end
end

and then another class to define the cattery itself, which internally stores an array of the cats currently in the cattery as well as providing an interface to add a new cat. Additionally, the cat should express itself by “speaking” after it is added to the cattery:

class Cattery
  def initialize
    @cats = []
  end

  def add_cat(cat)
    @cats << cat
    cat.speak!
  end
end

Let’s try it out:

cattery = Cattery.new
cattery.add_cat(Cat.new)

=> "meow!"

Lovely stuff.

Now imagine you discover that your cats keep escaping and you decide that the easiest way to stop this happening is to install a “door” on the cattery (assuming that the resident cats have not yet figured out how to open doors). So, you change your Cattery class accordingly by providing an interface to allow a door to be open and closed. You further alter your “add cat” method such that it will not allow a cat to be added unless the door is open:

class Cattery
  def initialize()
    @cats = []
    @door_open = false
  end

  def open_door
    @door_open = true
  end

  def close_door
    @door_open = false
  end

  def add_cat(cat)
    if @door_open
      @cats << cat
      cat.speak!
    else
      raise "Can't add a cat when the door is not open!"
    end
  end
end

Sweet. Now when you try adding a cat when the door is closed you get an error:

cattery.add_cat(Cat.new)
=> :in `add_cat': Can't add a cat when the door is not open! (RuntimeError)

cattery.open_door
cattery.add_cat(Cat.new)
=> "meow!"

Great! Nice and secure. only one problem… the developer who wrote that last piece of code forgot to close the door afterwards (doh!). How do we ensure that the door always gets closed properly after a cat is added?

Maybe you could use the begin/ensure (try/finally for non rubyists) syntax within the add_cat method? Well, if you go down that road then you’re breaking the single responsibility principle for that method – it’s called “Add cat” that’s all it should really be doing… but now it’s responsible for both adding the cat AND opening and closing the door. The method would also become coupled to the door interface which may cause future issues if we ever decide to change that interface or extract the door out into a class of its own. You might think that you could just remember to do a begin/ensure every time you add a cat:

begin
  cattery.open_door
  cattery.add_cat(Cat.new)
ensure
  cattery.close_door
end
=> "meow!"

But then you’re pretty much back in the boat you were originally, where you were relying on programmers to remember to close the door after themselves… only this time you have twice as much code!

At this point rubyists will start considering blocks. You might find yourself thinking along these lines :

* We could create a method to safely open the door and close the door afterwards, yielding to a block.
* We could remove the open/close methods on the cattery so people need to use that method to add a cat.

Such a method might look like this:

class Cattery
  ...

  def safely_open_door(&block)
    begin
      @door_open = true
      yield self
    ensure
      @door_open = false
    end
  end
 
  ...
end

Purrrfect. This would allow you to do the following:

cattery.safely_open_door do |this_cattery|
  cattery.add_cat(Cat.new)
  this_cattery.add_cat(Cat.new)
end

And you could stop right there – the solution works and the cats are safe. However, the code is not beautiful. We have multiple versions of the same variable floating around, both inside and outside of the block, which is confusing. It looks messy. Wouldn’t it be nicer if we could, just within the scope of the block, consider ourselves to be in the “cattery domain” where we could exclusively talk to the cattery without worrying about what’s going on outside of the block?

This is where instance_exec comes into play.

instance_exec changes the scope of the code within the block itself, and subsequently will change the result of calling “self” within it. In its current form, the block is scoped to the “main” object, which is why we are able to access the “cattery” variable.

What would be really nice is if this block were to be scoped to the cattery itself – any code within it would therefore be specific to the domain of dealing with a cattery. We can actually achieve this with one simple change to the code we have already:

class Cattery
  ...

  def safely_open_door(&block)
    begin
      @door_open = true
      instance_exec(&block)
    ensure
      @door_open = false
    end
  end
 
  ...
end

All we have changed is “yield” to “instance_exec”. The block will still be called (you can even pass additional arguments to the instance_exec method if you want to and they’ll be yielded to the block too). Making this small change allows us to finally write the code we want to:

cattery.safely_open_door do
  add_cat(Cat.new)
  add_cat(Cat.new)  
end

Or in one line:

cattery.safely_open_door { add_cat(Cat.new) }

Gorgeous.

So why would you ever want to do this? Well, the easiest way of demonstrating why you might want to create a DSL is to look at one you have already been using, maybe without even realising it. Try to imagine life without this syntax:

Rails.application.routes.draw do
  resources :products do 
    resources :comments
  end
end

Yup. The config.rb routes file in a rails application uses exactly the techniques that have been described here to create a language for you to talk about routing within the routes.rb file. If you output the result of “self” within the routing block you’ll find that it’s one of these:

 #<ActionDispatch::Routing::Mapper:0x000000040a4548>

Anyone who’s been in the game long enough to remember how routes worked in rails 2 may recall that previously routing used to work like this:

ActionController::Routing::Routes.draw do |map|
  map.connect '/products', :controller => 'products', :action => 'index'
  map.connect '/products/:id', :controller => 'products', :action => 'show'
end

And you’ll be hard-pressed to find anyone who wants to go back to that syntax. In conclusion then, instance_exec can help you:

* Write neater code
* Write less code
* Create rich Domain Specific Languages for you and other developers to use

PDF generation in rails 3 with prawn

Firstly, as always, there is a fantastic Railscast by Ryan Bates which explains Prawn perfectly. Having said that, there are a few things that it doesn’t mention that you need to do in order to use prawn in Rails 3. The path to getting this working is as follows;

#First install prawn on your system (lose the sudo if you're running under RVM)
sudo gem install prawn

#install the prawnto plugin
rails plugin install https://github.com/prior/prawnto.git

#add prawn to your Gemfile
gem "prawn"

After this, you should be able to do everything Ryan does in his railscast 🙂

Creating your own attr_accessor in Ruby

When going through Ruby 101, you won’t need to do much research before you come accross the use of the attr_accessor methods. There are several flavours of this;

attr_accessor gives you a getter and a setter
attr_reader just gives you a getter
attr_writer just gives you a setter

Here’s a code example of this functionality being used;

class Person
  attr_accessor :name, :age
end

#above class definition enables the following
p = Person.new
p.name = "Mikey"
p.age = 30
puts p.name

Magic. It’s almost like you’ve somehow managed to add two more methods to the person class without defining them. Well, it turns out that this is exactly what you have done! For anyone who is not used to dynamic programming languages (and I include myself in that list) this can be a really tricky point in the learning curve. This sort of functionality is used all the time in ruby, and not only within the context of attr_accessors – The Rails framework, for example, uses dynamic code to allow you to add very complex functionality to your ActiveRecord classes with a single line of code.

If you are anything like me, then you can’t just take the fact that it works for granted! I needed to know *exactly* how this sort of thing is possible! This post will clear up exactly how this attr_accessor magic works by showing you how to make your own version of the same functionality.

Dynamic code is created using a series of “eval” methods which the ruby language makes available to you. There are several flavours (eval, instance_eval, class_eval, module_eval) – the one we’ll be using here is class_eval, which you basically use to add code to a class. As we will be trying to create a method that will be accesible from all classes, we will need to add our code to the Class class (not a typo!). This is going to get a bit headswimmy, so I’ll just go ahead and show you the code itself then discuss it below.

class Class
  #firstly, the * decoration on the parameter variable
  #indicates that the parameters should come in as an array
  #of whatever was sent
  def mikeys_attr_accessor(*args)

    #We simply iterate through each passed in argument...
    args.each do |arg|
      
      #Here's the getter
      self.class_eval("def #{arg};@#{arg};end")
      
      #Here's the setter
      self.class_eval("def #{arg}=(val);@#{arg}=val;end")                      
                      
    end
  end
end

The above code allows a new class to be defined as follows;

class Person
  mikeys_attr_accessor :name, :age  
end

Which in turn allows you to write code like this;

person = Person.new
person.name = "Mikey"
person.age = 30
puts person.name
puts person.age

A lot was going on in the first code example, but the rest of it functions exactly as you would expect attr_accessor to function. The focus here will therefore be on the first bit of code. So it all starts off pretty basically, we are able in ruby to extend any class simply by using the class keyword. We then add the method “mikeys_attr_accessor” to it, using a bit of ruby syntactic sugar to allow this method to receive any number of arguments. It’s worth pointing out that we should really check that these arguments were symbols, but as this is a simple example I’ll skip that part.

Next we iterate through each argument and make two calls to the “class_eval” method. The message we send to this is basically just an interpolated string representing the code we want included in our object. Yes, I did say object – you might raise the question at this point as to why I’m using the word “object” when we are clearly adding a method to a class. You might also question the presence of the word “self” before the “class_eval” call, surely this would mean that we have somehow managed to create an “instance” of a class?!

This was pretty much the point, while learning Ruby, that I lost cabin pressure.

class Person
end

Person.class
=> Class

The capital letter at ths start of Person indicates that it is a constant. Person is constant instance of the Class class. As you’ve instantiated the Class class in your Person class, you need to use “self” on the class eval to make sure that the class_eval method is talking to the Person instantiation of the Class class. You may need to read the previous sentence a few times before it sinks in (if you feel your ears starting to bleed, contact your GP immediately).

A better question is that, if this is the case, why is class_eval used instead of instance_eval? the short answer to that is that it has to do with scope and context. If you are interested in learning a bit more about metaprogramming, i found the following question over on stack overflow to be incredibly useful. Lots of great links from the respondants.

http://stackoverflow.com/questions/788689/ruby-metaprogramming-online-tutorial

Readable Riddle in Ruby!

One of the main things that attracted me to the ruby language was how readable my code was, while at the same time retaining a tight structure and, most importantly, still being very fast. I decided to put this to the test by creating a piece of code that literally read like a passage of English text. The focus of this experiment was the “As I was going to St Ives” riddle. I’ll go into a bit more detail on the riddle itself in a second if you’re not familiar with it. The challenge here was not only to create “literally” readable code, but also to follow ruby best practices. Of course, the code would actually need to solve the riddle too 🙂

If you haven’t heard this riddle before, take a look at this and mull it over.

As I was going to St Ives
I met a man with seven wives
Every wife had seven sacks
Every sack had seven cats
Every cat had seven kits
Kits, cats, sacks, wives
How many were going to St Ives?

So exactly how readable was I able to get the code? Well, in a word, very.

And, check it out, it solves the riddle when run too!

Now, this is the point where the pedantic among you will point out that are multiple solutions to the riddle. I did not know about these other solutions when i first embarked on this experiment, basically growing up and hearing this riddle I always thought it was just a smartarse way of getting people to do maths for no reason, and that the answer was “one person, me”!

It turns out that there are actually a whole bunch of solutions based on the inherant grammatical ambiguity of the problem itself. For example, you could assume that all items and people encountered were also going to st ives. You might infer that “how many” applies only to sentient beings. You might also assume that the dude you met who had seven wives was alone, and just “told you about his wives” when you met him.

I filled my “some-facts” file with all sorts of superfluous code, almost parodying the amount of superfluous facts that are inherrent in the riddle itself if you assume that the correct answer is “one”. My personal favourite method was this one;

def as_i_was_going_to(place)
  @people_and_where_they_were_going[:me] = place
end

Having said that, I believe that it is possible to leave the “stives” file above completely untouched, and with only minimal changes to “the-facts” you could get the code figuring out whichever solution you wanted to interpret. In fact, I’m putting that out there as an open challenge to any bored coders or rubyists that fancy having a crack at it – code is available in the following git repo;

https://github.com/mikeyhogarth/St-Ives-Problem-Ruby

“%” notation for ruby literals

Many examples you will come accross in Ruby involve an odd “%” notation when declaring literals. The syntax is basically a % symbol followed by a pair of any type of bracket or other non alphanumeric character, with some contents between the brackets. All five of the following examples;

=> %{Hello World}
=> %<Hello World>
=> %(Hello World)
=> %[Hello World]
=> %?Hello World?

Will evaluate to the string “Hello World”. While any non alphanumeric character can be used (such as the ? above) you gain more readability using brackets because you can see the opening and closing nature of each bracket. There is one other benefit of using brackets which we’ll come on to in a bit.

Why is this useful? Well, the most obvious benefit is when escaping characters within string literals. The following, for example, would fail due to a syntax error because the string is considered closed when the interpreter encounters the second quote mark;

=> puts "Mikey considers inappropriate use of "quotation marks" in sentences to be a crime against hunanity"

In order to get that working, you’d need to escape the quotes, like so;

=> puts "Mikey considers inappropriate use of \"quotation marks\" in sentences to be a crime against hunanity"

The following, however, would work without the need to escape the quotes;

=> puts %{Mikey considers inappropriate use of "quotation marks" in sentences to be a crime against hunanity}

And just to come back to the second benefit of using brackets instead of other symbols, the following example would fail because the ? inside the literal is not escaped;

=> %?Hello?World?      #This fails
=> %?Hello\?World?     #This is fine because the inner ? is escaped

However, when using brackets, as long as the internal brackets balance then ruby will escape them for you;

=> %<Hello < World>        #This will break because the internal brackets arent' balanced
=> %{Hello {there} World}  #This works just fine!

Decorating the %

The % can be decorated with various mneumonics which further assist ruby in evaluating the contents. The tradition with these mneumonics is that they are alphabetic characters, and that when capitalized these pneumonics allow interpolation to occur. For example, the letter q is used for string literals, and Q for string literals that allow interpolation, as seen in this example. If you attempt interpolation without using the correct mneumonic, your interpolation will be escaped;

=> num = 2
=> %q{1+1=#{num}}      #evaluates to "1+1=\#{num}"
=> %Q{1+1=#{num}}      #evaluates to "1+1=2"

The two i find myself using the most are q and w, which identify strings and arrays respectively as follows;

q string
Q interpolated string
w array of strings
W interpolated array of strings

Just to give one final example of that array notation in action, it’ll basically evaluate the contents to an array of strings using whitespace as a seperator like this;

=> %w{This is an array}     #evaluates to ["this", "is", "an", "array"]

I have seen and used this notation extensively in requiring libraries. For example, the following;

require "rubygems"
require "hpricot"
require "rails"

could be re-written more readably like this;

%w{rubygems hpricot rails}.each { |lib| require lib }

Return multiple values from a ruby method

Another day, another bit of crazy ruby syntax. It is preferable (and often best practice) to generally return return one value from any method or function. That said, there are occasions where it does actually make sense to return multiple values. In other languages (and indeed, in ruby too) you can achieve this by returning an array or a dictionary/hash of results. In the case of arrays, Ruby provides this alternative syntax. I am not entirely sure that I personally find this more readable, but it definitely requires less code;

def multireturn
  return ["Hello", "World"]
end

a, b = multireturn    #this is where the magic happens...

puts "return 1: #{a}"
puts "return 2: #{b}"

This would output;

return 1: Hello
return 2: World