Pick the Right Tool for the task at Hand!

We’ve been told many times in our life that each tool is useful for certain tasks and using a tool for something unrelated or even somewhat related is not a very smart decision. For instance you do NOT use a hammer in order to cut a piece of wood! Maybe after a lot of struggling you will be successful (breaking it from a certain place you wanted maybe! 🙂 ) but when you say it out loud (like I did now) it seems even more ridiculous! But sometimes it is not as irrelevant as the hammer situation. You can achieve what you’re looking for or you can get to where you want, but with extra effort and more time, cost and energy that is necessary which can be avoided! Imagine you want to get from point A to point B in the following picture:

Traveling form point A to B

Point A to B

There are different ways to do that. One is the blue path and the other is the red path (and many more). Both are doing the job and get you to the destination but I’m sure everyone agrees that blue path is better and more effective (from time, cost, energy, etc. perspectives). It’s kind of the same concept as using the appropriate tool in order to do the task at hand. When you do not use the appropriate tool, you’re taking the red path, probably you would get to your destination but with much more struggling that is necessary! On my machine, I have a directory which I store the episodes of a show I’m watching in and each episode files are stored in a subdirectory named in the form of a four-digit number ####! For some weird reasons I need to know what are the last 3 episodes of the show that I have. There are two different tools that I can use in order to get this small task done. One is a simple program in whatever language I want. Lets say Ruby as an example and the code can be something like the following:

class LatestEpisodesFetcher
 def initialize(entries)
  @entries = entries
 end

 def fetch
  return [] if @entries.empty?
  last_three = @entries.map(&:to_i).sort[-3..-1]
  last_three.select { |num| num != 0 }
 end
end

print "#{LatestEpisodesFetcher.new(Dir.entries(".")).fetch}\n"

And the other is a simple Bash script which can look like the following:

#!/bin/bash

set -e
ls | grep -v "whatever you don't want" | 
     sort -n | 
     tail -3 | 
     xargs

It’s super clear which is the red path and which one is the blue path. You can tell that EVEN by just looking at them and not more detailed technical reasons (e.g Bash is taking advantage of some simple, very efficient and super-fast UNIX commands for working with file system and its structure directly but in case of the Ruby code in best case they are some thin wrappers around the appropriate system calls and some other data processing on the results) Of course you can write the Ruby code in a more succinct way and even probably a one liner in more idiomatic Ruby style but the code I put here is showing my point more explicitly, so I’m gonna leave it that way. UNIX commands are pretty great for doing fast and quick analysis on files and directories and you can extract some interesting information (not just the weird one I showed here) very efficiently in order to get some perspective. And the great philosophy of UNIX — Everything is doing ONLY one thing and does it WELL! – gives you the ability to mix/compose all these small programs to achieve great stuff. The point I’m trying to make is pretty simple: pick the right tool for the task at hand! To be honest it did not need me to preach this much about it and bore you! So, sorry for that and happy hacking 🙂

Nested Stubbing => Shouts for Refactoring

A lot of programmers write unit tests during the development and also a lot of programmers do Test Driven Development. One thing that we usually forget while programming is Listening to our Tests. If we listen carefully to our tests they will give us a lot of interesting hints and information and frankly that’s why a lot of people call it Test-Driven-Design because we can find useful points in our tests that will help us to have a better design.

I’m going to talk about one of those points that we can find out very easily by listening to our tests and will help us to have a better design and having a piece of information in its right place in our program. That certain point is Nested Stubbing which BTW happens a lot in our tests.

Lets say we are writing a twitter client app and all the communication through the network, OAuth related parts, calling Twitter API, fetching and storing tweets, etc. is being done in separated modules (Separation of Concerns and Single Responsibility Principle etc.)

We have also different kinds of presentations (views if you will) for this application. One of them is a Console Based presentation for taking a look at the tweets in terminal. One part of this presentation is taking the latest 10 tweets and rendering them (in whatever way you like) to the user. Obviously the rendering related code lives in its own place separated from the logic, data storage etc. Imagine we have a Console class which gets those latest tweets and give them to the renderer object in order to show them to the user (for brevity I remove some parts):

def show_latest_tweets
    last_ten = Tweet.order(‘created_at DESC’).limit(10)
    renderer.render_tweets(last_ten)
end

and lets say we have a test for this piece to make sure that this method is calling the right things:

it “fetches last 10 tweets and renders them” do
    latest_tweets = [t1, …, t10]
    ordered_tweets = stub(:limit).with(10) { latest_tweets }
    Tweet.stub(:order).with(‘created_at DESC’) { ordered_tweets }
    renderer.should_receive(:render).with(latest_tweets)
    console.show_latest_tweets
end

**

If you look at this code there is an obvious violation of  Law of Demeter happening. We know that when we call order on Tweet what is being returned has a limit method that we can call to limit the results. How can you easily detect this? BECAUSE WE’RE DOING A NESTED STUBBING IN OUR TEST. We are setting up a nested stub cause we setup ordered_tweets as a result of calling order on Tweet which is a stub itself. This tells us that we know TOO MUCH about the inside of Tweet class and its details at this level (Console class) which we should NOT!

Right now we’re using something like ActiveRecord as the ORM for storage part of the application but what if we change that later to something else? There’s a good chance in that new ORM the mechanism for doing the same thing (getting the latest 10 tweets) will be different and we need to change our code appropriately. But with this code that we wrote here we have to change Console class for changing our storage mechanism which does not make any sense. Console SHOULD NOT know anything about the details of storage and storage should NOT be a REASON of change for Console.

We need to have a layer which hides this information from Console and give him what he wants instead of Console reaching for that information through method chains (Tell, Don’t Ask). As you can see Tweet is like a model (if you will) in this application. And he’s the one who should know about the storage mechanism in this app (how to be stored, retrieved etc.) [Or even taking it further there can be a TweetRepository class which is specifically handling storage-related stuff for Tweet, kind of like a Façade Pattern between Tweet and DB/File/etc.]

We can add a method to Tweet class like the following:

def self.last_n_tweets(n)
    Tweet.order(‘created_at DESC’).limit(n)
end

So now lets rewrite our test based on this change:

it “fetches last 10 tweets and renders them” do
    latest_tweets = [t1, …, t10]
    Tweet.stub(:last_n_tweets).with(10) { latest_tweets }
    renderer.should_receive(:render).with(latest_tweets)
    console.show_latest_tweets
end

And now the code for it:

def show_latest_tweets
    last_ten = Tweet.last_n_tweets(10)
    renderer.render_tweets(last_ten)
end

First of all, we don’t have that nested stubbing in our test method but that’s not the point, if you pay attention you see that we eliminated the coupling and dependency of Console to the Storage mechanism and it doesn’t have any knowledge about that part anymore which is a big advantage. If we decide to change the data storage part of this application or change our ORM, that change will be hidden from Console or any client of this functionality (Tweet retrieving stuff etc.)! Console will still call Tweet.last_n_tweets and how’s that being implemented is none of its business and it doesn’t care.

As you saw listening to our test can have interesting results and nice design hints. Whenever you feel that your test is more work than it should be, or it doesn’t seem to be right or it’s hard to write the test for the target piece of code, that means there’s a design problem in our code (MOST OF THE TIMES). So we should fix the problem in the right place not struggle with making that test happen anyway. It’s time to stop preaching.

Hope that helps and happy hacking.

** This test contains more than one assertion which is usually not a good idea (there are exceptions depending on the situation like anything else in programming)!  I wrote those here to show how things are supposed to work in that piece of code!

Few more characters better than jumping around

This is a short post for pointing out a quick and handy little thing that I found helpful in some cases while programming.

Some people are religiously against comments and they know the existence of comments in the code as a sign that means the code is not readable! (I was in that group for a while as well :P)

That’s not necessarily a true thing to say or believe. Comments can also exist in a readable and clean code. And they can be very helpful. In one specific case that I want to mention here, they can save you some scrolling and jumping around the file in order to get a sense out of the code you’re reading.

I’m a huge fan of the statement: “Imagine the next reader of your code is a serial killer and he knows where you live!” I always try to make my code as readable as I can at the moment. I like to be able to get a sense of my code with a glance without any need to dig deeper. Of course this is hard to achieve 100 percent but I try to make it really close when I can. One of the things that I noticed in my test code is that some times in order to have DRY (Don’t Repeat Yourself) I extract out a helper method or a setup block for setting up some data that I need to reuse in different tests that I’m writing.

Imagine you’re having a model named Event and you’re testing some validation rules for this model. Instead of keep repeating some values for its attributes in every single test it’s a good practice to put that as a setup in a “let” block in rspec as following:

let(:attributes) do
    {
        event_type: “CreateEvent”,
        generated_at: sometime,
        event_no: 1
    }
end

and  just change the one that is relevant to the validation rule that you’re about to test in your current test like the following:

it “requires a type” do
    event = Event.new(attributes.merge(event_type: nil))
    event.should_not be_valid
end

This makes your tests less polluted with repetitive values for the attributes over and over again. It’s a small thing with almost a big effect in the code cleanness.

Sometimes having this setup block makes you to scroll and jump around the test code to realize what are the values cause you’re depending on them in order to understand the test you’re reading and trying to understand. Not always you need to know the values. For instance in the above test with a quick glance you see what’s going on and you don’t care what are the values for the attributes cause the only thing that is matter (being tested) here is that event_type can’t be nil and it’s a required attribute.

But sometimes you need to know what’s going on in the attributes. Imagine a scenario that you need each event have a unique value for the event_no attribute. And you wanna test it like the following:

it “needs a unique event_no” do
    event1 = Event.create!(attributes)
    event2 = Event.new(attributes.merge(event_no: 2))
    event2.should be_valid
end

Now here you cannot understand the complete picture with just a glance. You can guess it obviously and I want to make the code completely readable so the reader won’t have to think/guess as much as possible or she won’t have to jump around the code/file to realize what’s going on. When you see this you can guess that the first event (event1) has a different event_no value so that’s why the second event (event2) is valid. Which is totally fine but I don’t think there is any harm in being even finer when it’s the least amount of effort required in order to get there:

it “needs a unique event_no” do
    event1 = Event.create!(attributes) #=> event_no = 1
    event2 = Event.new(attributes.merget(event_not: 2))
    event2.should be_valid
end

That’s it!!! Now with this few characters you saved your life (if the reader was a serial killer and he was pissed by having to scroll up and see the value for event_no in attributes)

I’m sure you think this is TOO MUCH. But again since it’s the least amount of effort and it makes the code even cleaner and more readable than before why not?! It’s so tempting to make it like this and save some scrolling and jumping or unnecessary guessing! Cause this makes the reader to get COMPLETELY what’s going on with just a glance which in my opinion is the best level of readability in the code => Glance-Understandable!!!

Anyway, I stop preaching right now and that’s all I have to say about this. I hope that will be useful.

Just because you can, does not mean you should!

I tweeted about this thing a couple times and now I want to elaborate a little more on it with an example! A lot of times I hear people talking about the fact that something is much easier to do in a specific language and we can do it that way! And a lot of times that makes sense and is a good way to do that specific task in that specific language! But sometimes it’s just a violation of a principle that we’ve learned the hard way that it matters and we should be careful about it in our code base! For example imagine we want to write a user authenticator which determines whether user’s credentials are correct or not! You can see something similar to the following in a lot of code bases! (Remember that it’s just a very simple thing just for the sake of this post and by no means this is a user authenticator :D)

describe UserAuthenticator do
    it “does not authenticate with wrong password” do
        user = stub(:username => “bob”, :password => “pwd”)
        user_rep = stub(:get_user_by_username => user)
        DatabaseUserRepository.stub(:new => user_rep)
        authenticated = subject.authenticate(“bob”, “wrong password”)
        authenticated.should be_false
    end
end

class UserAuthenticator
    def initialize
        @user_rep = DatabaseUserRepository.new
    end

    def authenticate(username, password)
        user = @user_rep.get_user_by_username(username)
        password == user.password
    end
end

It’s not this easy to do such a thing in a static-type language like Java or C# but since ruby is a dynamic language (duck-type) so ruby and rspec let you do something like the above code! As long as it responds to “new” message you can stub it in any way you like so a lot of people just because they CAN do this they do something similar in their code! But we forgot the main point here! We are violating the Dependency Inversion Principle and instead of depending on abstraction we are tightly coupling ourselves to a concrete thing (DatabaseUserRepository)! I know that Dependency Inversion Principle in a dynamic language such as Ruby has a slightly different meaning and it’s not exactly as its meaning in Java or C#! But what matters for us here is something that can responds to the message “get_user_by_username”! That’s all that matters here! But we are making ourselves more dependent than what matters! Imagine we want to also support storing user information in flat files or some other mechanism! How are we gonna handle those parts of code for the same logic and functionality?! Are we gonna have another UserAuthenticator that instantiate FileUserRepository in its constructor and the rest will be the exact same?! Of course not and I can see you’re cringing right now! WTF?!

We have something which is exactly helpful in this kind of situation and it’s called Dependency Injection! (Of course there are other ways for handling this, e.g. Strategy Pattern, but I go with Dependency Injection for this post just for fun :D)

We inject the dependency and the only thing that matters to us is that it can respond to “get_user_by_username” message! So when it comes to support different kinds of storage mechanism and their appropriate repositories the code will be totally flexible in that scenario and all we need is a new instance of our UserAuthenticator with a FileUserRepository injected to it! So the code for such a design will be like the following:

describe UserAuthenticator do
    let(:user_rep) { stub }
    let(:authenticator) { UserAuthenticator.new(user_rep) }
    it “does not authenticate user with wrong password” do
        user = stub(:username => “bob”, :password => “pwd”)
        user_rep.stub(:get_user_by_username =>; user)
        authenticated = authenticator.authenticate(“bob”, “wrong password”)
        authenticated.should be_false
    end
end

class UserAuthenticator
    def  initialize(user_rep)
        @user_rep = user_rep
    end

    def authenticate(username, password)
        user = @user_rep.get_user_by_username(username)
        password == user.password
    end
end

The point is not just being able to write test for the code! The whole point of TDD is driving a better design for us so in a static-type language it’s not easy to do something like the first example hence it’s hard to write tests for it this way so it will drive us towards depending to abstraction and also injecting that dependency through constructor so we can easily replace the actual collaborator with a stub and test the unit of work that we want at the moment completely isolation! But because we can write a test like the first example in ruby and rspec it doesn’t mean we should do that! The point is having a better design not being able to write tests for the code!

Remember again, just because you can does NOT mean you SHOULD! Power brings responsibility so use the power in a right way and at the right place!

Something worth a try!

I hope you enjoyed it!