Beautiful Code

I've been working on a DSL for mock-based testing C recently. I'm writing it in Ruby and it's been coming along nicely.

I started with a Translator class that had an accept_line method. I used strings as lines for a while and then I got to the point where I had to report errors so it was time to add a Line class:

class Line
  attr_reader :text, :line_number, :file_name
  
  def initialize(text, line_number, file_name)
    @text = text
    @line_number = line_number
    @file_name = file_name
  end
end

After I started passing Lines rather than strings, I ran my tests and modified my code so that it worked correctly with them. Then, I started to report errors to an Errorhandler class.

Some people would pass the line to the Errorhandler like this:

handler.report(current_line, "Expected call or returns clause")

but then the Errorhandler would have to read all of the information from the Line and form the actual message.

Why not let Line do it. If it did, we wouldn't need readers for the attributes:

class Line  
  def initialize(text, line_number, file_name)
    @text = text
    @line_number = line_number
    @file_name = file_name
  end
  
  def form_message(message_text)
    "#{@file_name}(#{@line_number}): #{message_text}"
  end
end

A bit better. The only problem is that some client of Errorhandler will have to go to a Line object, ask it to form a message and then take that message and pass it to the Errorhandler. It might be cleaner to just have the Line report to an Errorhandler:

class Line
  def initialize(text, line_number, file_name)
    @text = text
    @line_number = line_number
    @file_name = file_name
  end
  
  def report_error(message_text, handler)
    handler.report("#{@file_name}(#{@line_number}): #{message_text}")
  end
end

This sort of thing is design at a lower level than many people are accustomed to. Typically, people think about concepts like Line and Errorhandler and they imagine that the first is data and the second is behavioral. But the truth is, concepts are whatever we make them. We can put behavior where it makes sense in service of a sounder protocol.

I can always tell when people have been working primarily at the conceptual level. As you look downward, there's a point at which design just stops. When I'm curious about people's design habits, I look for micro-design, the small decisions. They seem to be good indicators of attention.

Note to Ruby cognoscenti: I know the code would be shorter with a Struct, but I decided to keep the example less idiomatic for a wider audience. - mf

A few years ago, Martin Fowler and Eric Evans coined the term fluent interface. A fluent interface is a domain-specific language embedded in a programming language. Typically, it consists of a set of classes that have been organized to allow you to write code that nearly reads as English.

Steve Freeman and Nat Pryce’s JMock testing framework is a great example of a fluent interface. Read this code aloud and notice how different it is from most other code you've read aloud:

mockClock.expect(atLeastOnce())
        .method("getCurrentTime").withNoArguments();

Fluent interfaces present some very interesting design challenges. Here's a toy problem that highlights them.

Imagine that you are working in a language that doesn’t have numeric literals. Can you make a fluent interface which makes it easy to express numbers less than one million?

Here are some examples of valid numbers in Ruby.

one
two
twelve
twelve.hundred
one.hundred.thousand.and.fifteen
twelve.hundred.and.one
five.hundred.and.fifty.seven

You should be able to go to any of these and ask it for its value:

twelve.hundred.and.one.value

This seems like a nice code kata. I haven't tried it yet. I might if I have some time this week. It does, however, seem to lead to some interesting questions:

1. What qualities does a grammar need to have to create an embedded DSL which doesn’t allow nonsensical constructs? For example: we might allow the construct seven.and.six, knowing that it could evaluate to 13, but ideally, we would like to restrict the DSL to expressions that state numbers directly. Is this even possible for the number problem?
2. If there is a sensical fluent interface for this problem, what is the minimal number of classes needed to implement it, i.e., what is the fluent interface's cardinality? Does this number tell us anything about the grammar?

Talking about error handling is a bit like talking about taking out the trash. We all know that we have to do it, but we don’t really want to spend much time thinking about how we do it. It’s a shame, however, because there is nothing that makes code uglier and less maintainable than thoughtless error handling.

The industry recognizes that long method is a code smell, but seriously, how long would many of those methods be if they contained only the “happy path", the path that shows what the software is about? Most methods I encounter out in the field would be substantially shorter and they would be far more legible. You might say, “So what? We need error handling”, and I agree, but the fact is, it matters where we put it.

When I’m programming, I try to create something that I often call a trusted zone. The idea behind a trusted zone is that it is an area where you don’t have to check for much, because you can assume that you’ve been given the right parameters and that calls will succeed.

Trusted zones can be big or small. Sometimes I fight to get a single method that reads like an algorithm: it can be that way because I guarantee that everything it calls works or throws an exception that bypasses my method. Other times, I try to fashion trusted zones in a larger area of code, a cluster of classes or a component. The trick is to take all of the error detection that you can and push it to the periphery either structurally or temporally. Why, for instance, should I have to check for a read failure in the middle of my logic if can wrap the call and handle it before it returns? And, why should I check for a missing field in the middle of my logic if I can check the data structure before it ever gets there?

Trusted zones are social constructs as much as they are technical constructs. If you are working on a library or a framework, essentially something that is all API, and you don’t have any control over your callers, you can have only so much trust. On the other hand, if you are working in an application, you can often afford to separate the error handling concern as much as possible from the computational concerns. Error handling should be a matter of design, not an afterthought.

If you get a chance, look at some of your methods and see if you find any that do some work, yet are completely dominated by error handling. Would some separation of concerns help? Can you imagine a trusted zone in your code? Do you already have one?

A while ago, I read about a political study that was done back in the 1950s. In it, researchers followed a set of people undergoing a career change and tested their political views before and after the change. People who were going from blue-collar jobs to white-collar jobs tended to become more conservative after a while. People who went from white-collar jobs to blue-collar jobs tended to become more liberal. Where you sit influences your perspective.

What does this have to do with programming? Well, let's try something out.

How do you feel about this Java code?

public class GlazeObject implements Renderable {
    private ClassStore store = new DefaultClassStore();
    private Formatter formatter = new DefaultFormatter();
    
    public void setStore(ClassStore store) {
        this.store = store;
    }
     
    public void setFormatter(Formatter formatter) {
        this.formatter = formatter;
    }
	
    public void render()
        …
    }
}

Do the setters bother you?

Okay, how do you feel about this Ruby code?

class GlazeObject
  def initialize
    @store = DefaultStore.new
    @formatter = DefaultFormatter.new
  end

  def render
    ...
  end
end


Feel any different?

The fact of the matter, is that they both offer the same level of access protection.  In the Ruby class, you can open up GlazeObject at any time, even hundreds of lines after its declaration, and make its variables accessible:


class GlazeObject
  attr_accessor :store
end

def do_something   
  o = GlazeObject.new
  o.store = TerribleBadMaliciousStore.new
  ...
end


Yet, you won’t find too many Ruby developers who are freaked out by this.  You will, however, find Java developers who don’t like the setters.  And, odder still, you will find people who program in Java and Ruby who will insist that setters are evil and blithely ignore the fact that they always have all the access that they would have with a setter by default in Ruby.

The only explanation that I have for this is that we are biased by our languages.  When we see that a level of protection is available in a language, we feel an obligation to use it.  When it's not there, we don't seem to notice it.  Where you sit influences your perspective.