rafanoronha.speaking()

Tell me you are used to explicit your intent every time you write code, and probably I’m talking to a very skilled programmer.

Explicit intent is a quite simple concept.
Great news. Despite the simplicity, there are huge advantages on bringing it to our daily work.

When the intent of code is explicit, future maintenance of this code is kept at a very healthy level.

You know, things can be bad when we are working with poor code.
Lack of explicitness is probably one of the biggest clues indicating your code is in trouble.

Sadly I’m not sure this is something every good programmer is aware.
So I’ve decided to rant about it.

Let’s see how easy can be identifying lack of explicit intent.

Here is some testing code extracted from spree, an open-source e-commerce solution that seems to have a solid code base.
Hopefully you are used to write testing code and you know it should receive the same care as your production code.

require File.dirname(__FILE__) + '/../spec_helper.rb'

describe Payment do
  before(:each) do
    @order = Order.new
    @order.checkout_complete = true
    @order.stub!(:total).and_return(100)
    @payment = CreditcardPayment.new(:order => @order)
  end

  describe "save hook" do
    it "should mark order as paid if payment_total = total" do
      @order.stub!(:payment_total).and_return(100)
      @order.should_receive(:pay!)
      @payment.save
    end
    it "should mark order as paid if payment_total > total" do
      @order.stub!(:payment_total).and_return(101)
      @order.should_receive(:pay!)
      @payment.save
    end
    it "should not mark order as paid if payment_total < total" do
      @order.stub!(:payment_total).and_return(99)
      @order.should_not_receive(:pay!)
      @payment.save
    end
  end

end

Testing code wrote on top of rspec tends to be very expressive, being the intents of what is happening pretty explicit.
You can see it at this code.

But I have an issue with the setup code.
It failed in telling us what is happening at a first moment:

  before(:each) do
    @order = Order.new
    @order.checkout_complete = true
    @order.stub!(:total).and_return(100)
    @payment = CreditcardPayment.new(:order => @order)
  end

When looking for a good understanding of what is going on, we are enforced to follow the code at a low level.

And if this kind of issue propagate at the code base, programming productivity and focus may be affected.

I told you explicit intent is a quite simple concept.
It is also pretty easy to be applied:

require File.dirname(__FILE__) + '/../spec_helper.rb'

describe Payment do
  before(:each) do
    create_and_checkout_a_given_order
  end
  def create_and_checkout_a_given_order
    @order = Order.new
    @order.checkout_complete = true
    @order.stub!(:total).and_return(100)
    @payment = CreditcardPayment.new(:order => @order)
  end
  describe "save hook" do
    it "should mark order as paid if payment_total = total" do
      @order.stub!(:payment_total).and_return(100)
      @order.should_receive(:pay!)
      @payment.save
    end
    it "should mark order as paid if payment_total > total" do
      @order.stub!(:payment_total).and_return(101)
      @order.should_receive(:pay!)
      @payment.save
    end
    it "should not mark order as paid if payment_total < total" do
      @order.stub!(:payment_total).and_return(99)
      @order.should_not_receive(:pay!)
      @payment.save
    end
  end
end

What the heck? Giving a name to that piece of code is all we were required to do?

Yes, and now we can read this code without worrying about what is happening at some anonymous and mysterious piece of code.

Giving meaningful names to your code is a very powerful technique.
Having deserved a whole chapter at Clean Code, by Robert Martin.

So, when you understand exactly what is happening at some code you just get in touch, a very skilled programmer should be behind it.

Related posts:

1. The best code ever