We soon encountered a problem due to the fact that click events are rather slow to fire on the iPhone. There is a delay due to the fact that the iPhone waits for the user to complete a gesture before deciding that the intended gesture was in fact a click.

JQTouch uses divs to navigate between screens, so for example if you have the div

<div id="primary-view"></div>

you can simply navigate to it through a normal anchor link, and the transition will thanks to jQTouch be really “iPhone like”.

<a href="#primary-view">Primary view</a>

Our main problem is that we load our content dynamically through Ajax. So our links looked like this:

<a onclick="fetchContent();" href="#primary-view">Primary view</a>

This resulted in a race condition. The anchor link listens to the tap event which is fired much earlier than the click event, and therefore we mostly ended up in empty views. So we needed to replace all onclicks to ontap listeners. The problem then is that we could no longer test our webapp in a normal desktop based Safari browser.

So, we decided to happily go along and write inline onclick events on our links and other interaction elements. But while in the iPhone we see to it that the onClicks are removed and replaced with tap listeners.

That function looks like this:

function rebindClicks(){
    var userAgent = navigator.userAgent.toLowerCase();
    var isIphone = (userAgent.indexOf('iphone') != -1) ? true : false;
 
    if (isIphone) {
        // For each event with an inline onclick
        $('[onclick]').each(function() {
            var onclick = $(this).attr('onclick');
            $(this).removeAttr('onclick'); // Remove the onclick attribute
            $(this).bind("click", preventClickEvent); // See to it that clicks never happen
            $(this).bind('tap', onclick); // Point taps to the onclick
        });
    }
}
 
function preventClickEvent(event)  {
    event.preventDefault();
}

We now call this little function everytime the DOM is changed. If something turns up with an inline onclick. It is will be rerouted by jQuery to a tap listener instead.

Again, we felt we needed to do this because many of our developers do not have a Mac (and hence do not have the iPhone simulator). And testing on the iPhone can be really time consuming. So for testing during development we wanted to use onClick, and when testing on iPhone we wanted to use taps instead.

But the biggest bonus was without a doubt that things are overall much faster in the web application. Taps fire much faster than clicks in the iPhone.

Here’s how it looks running the same app both in desktop safari and embedded into the iPhone simulator.

The fourth rule of the exercise is to only use one dot per line. Why is that important? Well apart from the apparent readability increase, many dots one one line can signify that an activity is happening in the wrong place. Or maybe your object is dealing with two other objects at the same time.

In both these cases you are not fully implementing the object oriented paradigm. Objects are supposed to know something about their immediate “friends” but not about their friend’s friends.

This is an example of a quite broken implementation.

public class TimeLineObject extends UIComponent {
    ....
    public function redraw():void {
        TimeLineDrawer.theInstance.drawTimeLine(TimeLineDrawer.theInstance.timeLineCanvas);
    }
}

To follow the rule of this exercise you might be tempted to remove the number of dots per line by doing something like this:

public class TimeLineObject extends UIComponent {
    ....
    public function redraw():void {
        var timeLineDrawerSingleton:TimeLineDrawer = TimeLineDrawer.theInstance;
        var canvas:Canvas = timeLineDrawerSingleton.timeLineCanvas;
        timeLineDrawerSingleton.drawTimeLine(canvas);
    }
}

But this is hardly the point. It is very apparent in the above example that the activity as a whole is not in the correct place. In the TimeLineObject we are suddenly telling some remote singleton static object to carry out things for us. Our object knows to much and the architecture has in fact failed at some earlier point.

The example from the Thoughtworks book is excellent. It shows the correct way to think about the exercise, namely to put activities in its right place. I will quote it below. First the “erroneous” example:

class Board {
  ...
  class Piece {
     ...
     String representation;
  }
  class Location {
      ...
      Piece current;
  }
  String boardRepresentation() {
      StringBuffer buf = new StringBuffer();
      for(Location l : squares())
      {
          // Oh lord lots of dots here... :)
          buf.append(l.current.representation.substring(0, 1));
      }
      return buf.toString();
  }
}

Applying the rules of having one dot per line here actually means REAL refactoring. I.e putting stuff where it belongs. And that is usually in other classes. Here’s the refactored example:

class Board {
   ...
   class Piece {
      ...
      private String representation;
 
      String character() {
          return representation.substring(0, 1);
      }
      void addTo(StringBuffer buf) {
          buf.append(character());
      }
   }
 
   class Location {
      ...
      private Piece current;
 
      void addTo(StringBuffer buf) {
          current.addTo(buf);
      }
   }
 
   String boardRepresentation() {
       StringBuffer buf = new StringBuffer();
       for(Location l : squares())
           l.addTo(buf);
       return buf.toString();
   }
}

So, the lesson from this exercise is that you should put activities where they belong. Avoid using static utility classes and other “middleman” objects. And make sure that the object you are working in does not now to much about other object’s activities. Couple this with the previous rules and you have gone far in a sturdy, nice looking design.

Previous « Rule 3: Wrap All Primitives and Strings
Next » Rule 5: Don’t Abbreviate

Wrapping primitives (ints, floats etc) and strings is an easy way to increase maintainability and readability of your code. Also, as Abinesh TD has commented below, wrapping expresses intent of data, preventing misuse. Consider for example the following pseudo-javacode:

public class Contact {
    private String emailAddress;
 
    public void setEmail(String emailAddress) throws InvalidEmailException {
        if (! validateEmail(emailAddress)) {
            throw new InvalidEmailException("Uhm, that's not a valid mail address...");
        }
 
        this.emailAddress = emailAddress;
    }
 
    public String getEmail() {
        return emailAddress;
    }
 
    private Boolean validateEmail(String emailAddress) {
        // TODO: validation regexp etc
    }
}

A very simple class, containing a single field intended to hold an email address. It looks good enough, but imagine that you have other places where you would need to validate and store email addresses. You would have a tendency for code duplication right there.

Worst case would be that you would have a validation function in every email container class. It would be better to wrap the string intended to hold the email address in its own class, even if it only holds one field, the potential for code reuse increases exponentially.

A better implementation could look like this:

public class Contact {
    private EmailAddress emailAddress;
 
    public void setEmail(EmailAddress emailAddress) {
        this.emailAddress = emailAddress;
    }
 
    public void setEmail(String emailAddress) {
    try {
        this.emailAddress = new EmailAddress(emailAddress);
    } catch (InvalidEmailException e) {
        // Oh lord something went wrong here... :)
    }
 
    public String getEmail() {
        return emailAddress;
    }
}

The benefits should be immediately clear. Suddenly the class EmailAddress requires the email address string to be valid to be instantiated at all. This would make it much easier to quickly zero in on bugs and also increases the potential reuse of your code.

Pretty much any variable you want to store, whether it is a primitive or a string – WILL need some sort of validation. This is a major reason for wrapping them. But other than that, consistently wrapping gives your object oriented code a higher degree of encapsulation.

Previous « Rule 2: Don’t Use the Else Keyword
Next » Rule 4: Only Use One Dot Per Line

The second rule of the “Nine Ways to Better Software Today” is to stop using

else

This builds on top of rule 1, to decrease the level on indentation by again focusing on minimizing complex conditionals. Within the object oriented paradigm, polymorphism is a powerful model to handle this. Regardless of programming model,  this exercise forces you as developer to find alternatives to using the else keyword and thus considerably beautifying your code.

Consider the following Python code

def set_member_status(member, status):
    """ Spot the else keyword """
 
    if is_active(member):
        do_something(member, status)
    else:
        do_something_else(member, status)

There are several ways to simplify this method. For simple cases use early returns, as below. Early returns only work in methods which are short and lacking in complexity (keeping down the level of indentation helps with this). Once a method is long and contains many levels of abstraction, early returns can of course not be used. But by then you’ve failed at this exercise anyway.

def set_member_status(member, status):
    """ Example of using early returns """
 
    if is_active(member):
        do_something(member, status)
        return # here is the early return :)
 
    do_something_else(member, status)

In many languages it is possible to use the ternary operator. That would look something like this (in javascript):

/** Wrong */
function drowned() {
  if (timeInWater < SURVIVABLE_TIME) {
    return false;
  } else {
    return true;
  }
}
 
/** Right */
function drowned() {
   return timeInWater < 10 ? false : true;
}

Guard clauses is another way of increasing readability. The following example is taken from here

double getPayAmount() {
    double result;
    if (_isDead) result = deadAmount();
    else {
        if (_isSeparated) result = separatedAmount();
        else {
            if (_isRetired) result = retiredAmount();
	    else result = normalPayAmount();
        };
    }
    return result;
};	
 
double getPayAmount() {
	if (_isDead) return deadAmount();
	if (_isSeparated) return separatedAmount();
	if (_isRetired) return retiredAmount();
	return normalPayAmount();
};

Previous « Rule 1: Only Use One Level of Indentation
Next » Rule 3: Wrap All Primitives and Strings

On reading their book, the Thoughtworks Anthology there was one chapter (Object Calisthenics by Jeff Bay) which struck me as extremely fun to read, it contained an exercise called “Nine Steps to Better Software Design Today”. An exercise completely focused on object oriented design quality with all that that entails, like encapsulation and appropriate use of polymorphism.

It is really a very simple exercise in many aspects, it simply provides nine rules, and asks me as a developer to do my absolute best to abide by those rules. What Thoughtworks does is so ingenious. Instead of just preaching the holy grail of object oriented programming, they ask me to be a part of the sermon. On reading the whole exercise I was instantly revving my engine to actually do the exercise. So I started up a small GWT project and forced myself to actually try and comply with the nine rules.

I’ve never had so much fun programming! And the process truly changed the way I will write code from now, whether it is in a purely object oriented language or not.

Said and done. I will start with the first rule:

Rule 1 : Use only one level of indentation per method

No matter which language you are working with, this is something that is very important. Check out the class, that thoughtworks uses as an example, below. It contains one function with several levels of indentation.

class Board {
  String board() {
    StringBuffer buf = new StringBuffer();
    for (int i = 0; i < 10; i++) {
      for (int j = 0; j < 10; j++)
        buf.append(data[i][j]);
      buf.append("\n");
    }
    return buf.toString();
  }
}

Now consider that after some refactoring the code could look like this:

class Board {
 String board() {
  StringBuffer buf = new StringBuffer();
  collectRows(buf);
  return buf.toString();
 }
 
 void collectRows(StringBuffer buf) {
  for (int i = 0; i < 10; i++)
   collectRow(buf, i);
 }
 
 void collectRow(StringBuffer buf, int row) {
  for (int i = 0; i < 10; i++)
   buf.append(data[row][i]);
  buf.append("\n");
 }
}

What basically has happened here is that methods have been extracted for each level of indentation. The whole class is so much more readable, unit testable, understandable… you name it. Or as the authors of the chapter puts it:

Try to ensure that each method does exactly one thing. One control structure, or one block of statements per method. [Heavy indentation] in a method [is] a signal that you’re working at multiple level of abstraction, and that means you’re doing more than one thing.
…
Working with methods that do exactly one thing, and classes doing exactly one thing, your code begins to change, [...] increasing exponentially the level of reuse.

Next time I will talk about rule 2: Don’t use the else keyword