Creating and publishing your first ruby gem

Introduction

In this post I’m going to cover the basics of creating and publishing a gem using the bundle gem command provided by Bundler. We’re going to use bundler to create a gem template for us. We’ll then take that skeleton gem, add some functionality to it, and publish it for all the world to use.

For the purposes of this tutorial I need a very simple example of something which you could conceivably want to release as a gem. How about a simple Sinatra web app which tells you the time? Sure, that’ll work. We’ll call it Didactic Clock. In order to make this server implementation need more a couple of lines of code we’ll add the requirement that the clock tells you the time in a verbose form like “34 minutes past 4 o’clock, AM”.

Preparing to create a gem

A great way to create and test gems in a clean environment is to use the awesome rvm and in particular rvm’s awesome gemset feature. I assume you’re already set up with rvm. If not go get set up now!

First off we’ll create a seperate gemset so that we can create and install our gem in a clean environment and be sure that someone installing our gem will have all the dependencies they need provided to them. We’re going to be creating a gem called didactic_clock, so we’ll name our gemset similarly. We’ll create the gemset and start using it by executing:

 rvm gemset create didactic_clock
 rvm gemset use didactic_clock

From now on I’ll assume we’re always using this clean-room gemset.

Creating the skeleton

First lets install bundler into our gemset:

gem install bundler

Now we’ll ask bundler to create the skeleton of a gem. In this tutorial we’re going to be creating a gem called didactic_clock. We’ll ask bundler to create a skeleton for a gem with that name by calling:

bundle gem didactic_clock

You should see some output like:

  create  didactic_clock/Gemfile
  create  didactic_clock/Rakefile
  create  didactic_clock/.gitignore
  create  didactic_clock/didactic_clock.gemspec
  create  didactic_clock/lib/didactic_clock.rb
  create  didactic_clock/lib/didactic_clock/version.rb
Initializating git repo in /Users/pete/git/didactic_clock

Modifying our gemspec

Bundler creates a basic .gemspec file which contains metadata about the gem you are creating. There are a few parts of that file which we need to modify. Let’s open it up and see what it looks like:

 
   # -*- encoding: utf-8 -*-
   $:.push File.expand_path("../lib", __FILE__)
   require "didactic_clock/version"
 
   Gem::Specification.new do |s|
    s.name        = "didactic_clock"
    s.version     = DidacticClock::VERSION
    s.platform    = Gem::Platform::RUBY
    s.authors     = ["TODO: Write your name"]
    s.email       = ["TODO: Write your email address"]
    s.homepage    = "http://rubygems.org/gems/didactic_clock"
    s.summary     = %q{TODO: Write a gem summary}
    s.description = %q{TODO: Write a gem description}
 
    s.rubyforge_project = "didactic_clock"
 
    s.files         = `git ls-files`.split("\n")
    s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
    s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
    s.require_paths = ["lib"]
   end

You can see that Bundler has set up some sensible defaults for pretty much everything. Note how your gem version information is pulled out of a constant which Bundler was nice enough to define for you within a file called version.rb. You should be sure to update that version whenever you publish any changes to your gem. Follow the principles of Semantic Versioning.

Also note that there are some TODOs in the authors, email, summary, and description fields. You should update those as appropriate. Everything else can be left as is for the time being.

Adding a class to our lib

We’ll start by creating a TimeKeeper class which will report the current time in the verbose format we want the Didactic Clock server to use. To avoid polluting the client code’s namespace it is important to put all the classes within your gem in an enclosing namespace module. In our case the namespace module would be DidacticClock, so we’re creating a class called DidacticClock::TimeKeeper. Another convention which is important to follow when creating gems is to keep all your library classes inside a folder named after your gem. This avoids polluting your client’s load path when your gem’s lib path is added to it by rubygems. So taking both of these conventions together we’ll be creating a DidacticClock::TimeKeeper class in a file located at lib/didactic_clock/time_keeper.rb. Here’s what that file looks like:

 
    module DidacticClock
    class TimeKeeper
     def verbose_time
      time = Time.now
      minute = time.min
      hour = time.hour % 12
      meridian_indicator = time.hour < 12 ? 'AM' : 'PM'
 
      "#{minute} minutes past #{hour} o'clock, #{meridian_indicator}"
     end
    end
   end

Adding a script to our bin

We want users of our gem to be able to launch our web app in sinatra’s default http server by just typing didactic_clock_server at the command line. In order to achieve that we’ll add a script to our gem’s bin directory. When the user installs our gem the rubygems system will do whatever magic is required such that the user can execute the script from the command line. This is the same magic that adds the spec command when you install the rspec gem, for example.

So we’ll save the following to bin/didactic_clock_server

 
   #!/usr/bin/env ruby
 
   require 'sinatra'
   require 'didactic_clock/time_keeper'
 
   # otherwise sinatra won't always automagically launch its embedded 
   # http server when this script is executed
   set :run, true
 
   get '/' do
    time_keeper = DidacticClock::TimeKeeper.new
    return time_keeper.verbose_time
   end

Note that we require in other gems as normal, we don’t require rubygems, and that we don’t do any tricks with relative paths or File.dirname(__FILE__) or anything like that when requiring in our TimeKeeper class. Rubygems handles all that for us by setting up the load path correctly.

Adding a dependency

Our little web app uses Sinatra to serve up the time, so obviously we need the Sinatra gem installed in order for our own gem to work. We can easily express that dependency by adding the following line to our .gemspec:

s.add_dependency "sinatra"

Now Rubygems will ensure that sinatra is installed whenever anyone installs our didactic_clock gem.

Building the gem and testing it locally

At this point we’re done writing code. Bundler created a git repo as part of the bundle gem command. Let’s check in our changes to the git repo. git commit -a should do the trick, but obviously feel free to use whatever git-fu you prefer.

Now we’re ready to build the gem and try it out. Make sure you’re still in the clean-room gemset we created earlier, and then run:

rake install

to build our didactic_clock gem and install it into our system (which in our case means installing it into our didactic_clock gemset). If we run gem list at this point we should see didactic_clock in our list of gems, along with sinatra (which will have been installed as a dependency).

Now we’re ready to run our app by calling didactic_clock_server from the command line. We should see sinatra start up, and if we visit http://localhost:4567/ we should see our app reporting the time in our verbose format. Victory!

Publishing our gem

The last step is to share our creation with the world. Before we do that you’ll need to set up rubygems in your system to publish gems. The instructions at rubygems.org are easy to follow.

Bundler provides a rake publish task which automates the steps you would typically take when publishing a version of your gem, but it’s fairly opinionated in how it does so. The task will tag your current git commit, push from your local git repo to some upstream repo (most likely in github), and then finally build your gem and publish your .gem to rubygems.org. If you don’t have an upstream repo configured then you’ll probably get an error like:

   rake aborted!
   Couldn't git push. `git push  2>&1' failed with the following output:
 
   fatal: No destination configured to push to.

So, now would be the time to set up an upstream repo. Doing that with github is really straightforward. Once you have your local git repo configured with an upstream repo you can finally publish your gem with rake publish.

Now anyone who wants to install your gem can do so with a simple gem install command. Congratulations! Fame and fortune await you!

Conclusion

Hopefully I’ve shown that creating and publishing a well-behaved gem is pretty simple. The didactic_clock sample I created is up on github, and of course the gem is published on rubygems.org and can be installed with gem install didactic_clock.

timestamped-scenarios, a custom Cucumber formatter

I just published a new Ruby gem called timestamped-scenarios. As usual the code is also available on github.

What's this gem for?

This gem provides custom cucumber formatters which append a test run timestamp to each scenario name as it is generated. a Timestamped::PrettyFormatter and Timestamped::HtmlFormatter are supplied already, but you can use the AddsTimestamp module to dynamically add timestamping to pretty much any Cucumber formatter.

You might wonder why I created these formatters. I'm currently working on an iOS project where we are using Frank and Cucumber to run automated acceptance tests against the application. We have integrated these acceptance tests into our CI build, and as part of that integration we record a screen capture movie of each test run. By adding timestamps to each scenario name we can easily skip to the part of the movie which shows that scenario executing. This is useful when trying to figure out the context around why a
specific scenario failed.

How do you use it?

As with my other cucumber formatter gem (slowhandcuke), getting set up with timestamped-scenarios is super easy. just install the gem with

gem install timestamped-scenarios

and you're ready to use them by executing cucumber with something like

cucumber --format 'Timestamped::HtmlFormatter' --out cucumber.html

You can also add these parameters to your rake cucumber task, or to your cucumber.yml config file. There's also a little sample project in the timestamped-scenarios repo on github which shows how to use the formatters.

What's it look like?

Here's an example of what the Timestamped::PrettyFormatter output looks like:

∴  cucumber 
Using the default profile...
Feature: demonstration

  Scenario: The First [0:00]      # the.feature:3
    Given I wait 5 seconds # step_definitions/steps.rb:1

  Scenario: The Second [0:05]       # the.feature:6
    Given I wait 0.7 seconds # step_definitions/steps.rb:1
    Given I wait 3 seconds   # step_definitions/steps.rb:1

  Scenario: The Third [0:09] # the.feature:10

3 scenarios (3 passed)
3 steps (3 passed)
0m8.709s

Objective C memory errors pt II - Dangling Pointers

In my last post I talked about memory leaks in Objective C. In this post I'll take about the converse - dangling pointers. In iOS a dangling pointer happens when you maintain a reference to an object which has been deallocated. I'd say the most common cause is failure to take ownership of an object you intend to maintain a reference to. Another common cause is when an object is accidently released multiple times by the same owner, leading to its retain count dropping to 0 and the object being deallocated before all the objects which hold references to the object release those references.

I'm going to illustrate this first type of dangling pointer bug (failing to take ownership of a reference) and try to explain in detail the cause of the error and its effects. We'll use a pedagogical Duck class similar to the one in my previous post:

@interface Duck : NSObject {
  NSArray *_feathers;
}
@end

We have a Duck which holds a reference to an array of feathers. We'd like to ensure that our Duck's feathers array always points to a valid NSArray instance, so we set the reference to an empty array during construction:

- (id) init
{
  self = [super init];
  if (self != nil) {
    _feathers = [NSArray array];
  }
  return self;
}

Once again we have a memory bug here, but this time it's the flip side of the memory management coin from a memory leak - a dangling pointer. Instead of failing to relinquish ownership of a reference we're failing to take ownership. We are asking NSArray to create an instance using the [NSArray array] factory method, which does NOT transfer any ownership to the caller. This is explained quite clearly in Apple's Memory Management Rules - if a method does not start with alloc, new or copy then the caller is not automatically granted ownership of the object, and should take that ownership explicitly by calling retain if it intends to maintain a reference to that object.

I'll illustrate one scenario of how this bug could manifest itself:

1) In our init method we call [NSArray array] which creates an NSArray instance. The creator of the array inside the implementation of [NSArray array] has to keep ownership of the instance for a certain period of time, otherwise its retain count would drop to 0 and it would immediately be deallocated.

2) still in the init method, we update _feathers to refer to the array, but neglect to take any ownership of the array.

3) at some later point while Duck is still alive the creator (and sole owner) of the array instance relinquishes its ownership of the array instance, dropping the array's retain count down to 0. This might be because it has been deallocated, or maybe it is replacing its reference to the array with something else, or some other reason.

4) The array's retain count has dropped to 0, so it is immediately deallocated and its memory reclaimed for future use by the memory management system. Our Duck instance has no way of knowing this, and is still holding a reference to where the array used to be. This is the dangling pointer.

Subsequently when the Duck instance attempts to talk to that array it is going to find itself talking to some random object, or just to arbitrary junk data. Crashes will ensue... eventually.

Note that the sole owner of the array as shown in the diagrams would in a lot of cases be an autorelease pool. This is because the easiest way to handle memory management when implementing factory methods like [NSArray array] is to create the object to be returned using alloc, and then transfer ownership to the autorelease pool before returning the object, like so:

+ (NSArray *) array {
  return [[[NSArray alloc]init]autorelease];
}

What makes this kind of dangling pointer error particularly tricky is that in certain use cases it will not manifest at all. If the usage of Duck is such that it always goes out of scope before the NSArray instance is deallocated then no issues will be detected. This could happen if the Duck instance and the NSArray instance it references are both owned by the same autorelease pool, for instance. However, when the usage patterns of Duck change you could suddenly see errors - even if you haven't changed the (buggy) implementation of the Duck class itself in months!

What should we have done?

Use an object creation method which implicitly grants ownership to the caller

- (id) init
{
  self = [super init];
  if (self != nil) {
    _feathers = [[NSArray alloc]init];
  }
  return self;
}

Use retain to explicitly take ownership

- (id) init
{
  self = [super init];
  if (self != nil) {
    _feathers = [[NSArray array] retain];
  }
  return self;
}

Common Objective-C memory management errors, Part I

I would say that the steepest learning curve for someone new to iOS development is having to manage your own memory using reference counting. Knowing when to retain and when to autorelease can seem like a black art until you understand the conventions which is used (extremely consistently, I might add) within Objective C libraries. Let's examine one very common mistake, which I will call the Property Assignment Memory Leak. I've seen this a few times, and indeed committed this error myself during my first weeks of iOS development.

The code

Imagine we have a simple Duck class, which holds a feathers array:

@interface Duck : NSObject {
  NSArray *_feathers;
}
@property (nonatomic,retain) NSArray *feathers;
@end

@implementation Duck
@synthesize feathers=_feathers;
@end

during construction we'd like to initialize this array, so we create an init method as follows:

- (id) init
{
  self = [super init];
  if (self != nil) {
    self.feathers = [[NSArray alloc] init];
  }
  return self;
}

Of course, we need to make sure we release our ownership of the feather array during deallocation, so we'll add a dealloc method like so:

- (void)dealloc {
  self.feathers = nil;
}

The Leak

So we're good here, right? The observant reader will note that no, we're not. the feathers array which we created in our init method will never be released. This will be a little easier to explain if I refactor the init method a little, making it more verbose by introducing a local variable to hold the array we are about to assign to the self.feathers property:

- (id) init
{
  self = [super init];
  if (self != nil) {
    // alloc will always create an object with a retain count already set to 1. In other 
    // words, tempArray has ownership of the object.
    NSArray *tempArray = [[NSArray alloc] init]; 

    // assigning to self.feathers bumps the array's retain count up to 2. In other words, 
    // now the feathers property also has ownership of the object.
    self.feathers = tempArray; 
  }

  // when we return tempArray goes out of scope without ever releasing ownership of the object it created. Memory leak!
  return self;
}

To make this clearer, I'll try and illustrate what happens as we move through the Duck object's lifecycle.

1) Here an instance of Duck has just been alloced, and we're about to execute init.

2) We create an array, and assign it to the local tempArray variable. Note that any objects created with alloc will already have a retain count of +1 when alloc returns.

3) We assign the array to the feathers property. Because the property has retain semantics it will take ownership of the array, incrementing its retain count to +2.

4) We've now left the init method, and so the local tempArray variable has gone out of scope. However, it never released ownership of the array before it went out of scope, so the retain count is still +2.

5) After using our Duck instance for some time it is eventually deallocated, at which point its dealloc method is called. We do the right thing and set its feather property to nil during dealloc. Again, the feather property has retain semantics and therefore it will release ownership of whatever it is currently pointing to just before taking ownership of whatever it is being asked to point to. It was pointing to our array, and is now pointing to nil, so it releases ownership of the array (dropping its retain count down to +1), and takes ownership of nil (which has no effect whatsoever).

6) Finally, our Duck instance is fully deallocated, and disappears. But our array instance still has a retain count of +1, even thought nothing is referencing it. Memory leak!

While I showed the entire lifecycle for a Duck instance here I should note that the bug is in the init method, and once that method returns the damage has been done. The fact that after init returns the array instance only has 1 reference pointing to it but has a retain count of 2 is indicative of that. I wanted to show the entire lifecycle to demonstrate that the point at which a memory leak is introduced will likely be quite far away from the point where the leak is detected. This is important to know when using Instruments or some other tool to try and detect leaks at runtime.

I think that the most common cause of this particular memory leak bug is an unclear understanding of how properties work. It is hard at first glance to see how assigning an object pointer to self.foo is different than assigning that pointer to a local variable. Once you grok that that property assignment also assigns ownership, and that you already have an implied ownership by the act of calling alloc then things start to fall into place. At least, that's what happened for me.

What should we have done?

We have a range of options for correctly implementing our init method:

Use autorelease

- (id) init
{
  self = [super init];
  if (self != nil) {
    self.feathers = [[[NSArray alloc] init] autorelease];
  }
  return self;
}

Explicitly release ownership after assignment

- (id) init
{
self = [super init];
  if (self != nil) {
    NSArray *tempArray = [[NSArray alloc] init]; 
    self.feathers = tempArray;
    [tempArray release];
  }
  return self;
}

Create an array without implicitly taking ownership

- (id) init
{
  self = [super init];
  if (self != nil) {
    self.feathers = [NSArray array];
  }
  return self;
}

The first two approaches are the most common. I often see advice to use the more verbose explicit release approach, rather than autorelease, because it is more performant. Personally, I tend to optimize for developer performance at the sake of a bit of CPU performance, and prefer the autorelease approach. It's a lot less typing and more importantly I feel it makes the code a bit easier to scan through, particularly if you have a block of code with lots of property assignments.

UPDATE

After posting this I remembered there's another way we could solve this memory leak:

Assign directly to the member variable

- (id) init
{
  self = [super init];
  if (self != nil) {
    _feathers = [[NSArray alloc] init];
  }
  return self;
}

I don't really like this approach, because there's a lack of symmetry in sometimes accessing a member variable directly, but at other times via a property. Also, it encourages folk to use this approach outside of init methods. This greatly increases the likelihood of another memory management error - not releasing ownership from an existing reference before replacing that reference. Hmm, I should cover that one in a future post...

Podcast about Frank and test automation on iOS

Some colleagues at Thoughtworks and I recently recorded a 30 minute podcast about Frank, our UI automation tool for iPhone/iPad testing which I introduced in this post.

In the podcast we cover:

• an overview of Frank, what it is and where it came from.
• How our testers and developers use Frank and cucumber at our current client (and how we'd ideally like to be using it).
• Alternatives to Frank, such as iCuke and brominet.
• Some waffling by me about some of the reasoning that drove my design decisions with Frank. For example, avoiding XML and XPath for UI element selection.
• Symbiote, the little web app that we embed inside Frank which allows a test creator to inspect and play with the live iOS app as it's running.
• Writing cucumber feature files per-story versus per-feature.
• Handling the stateful nature of an iOS app in UI-level tests, and including Frank testing into a Continuous Integration system.
• The challenges of testing an app which integrates with large back-end systems.
• What's next for Frank.

Many thanks to Chris Stephenson for organizing and facilitating, and to Derek and Hiyasmin for tolerating my hogging of the mike!

You can get more information on the podcast and give it a listen here.

Frank: Automated Acceptance Tests for iPhone and iPad

Recently I joined a team developing an iPad application. The application had no existing automated tests, and the team was under a tight deadline to deliver on promised functionality. Faced with similar circumstances in the past I have advocated introducing automated UI-driven acceptance tests to establish a loose but broad test coverage net. After a brief investigation we decided that the available tools weren't quite what we needed, so we built our own 'Frankenstein's Monster' by plumbing together several existing open source libraries to create a light-weight UI automation framework for iPhone and iPad applications, called Frank.

How does Frank work?

In use Frank consists of two main parts. There is a small objective-C server which is compiled into the iOS application you want to automate. You then use a remote driver from within your automated testing framework of choice to send automation commands to the Frank server and interpret the responses sent back.

Currently the project includes a Cucumber driver. Creating additional drivers (for RSpec, NUnit or JBehave perhaps) is a pretty trivial task, as the Frank server provides just a few key commands.

I don't get it. Show me moving pictures!

Here is a brief screencast which demonstrates a Cucumber test suite exercising the functionality of a simple iPhone app via Frank. [Click Here to watch the screencast in a larger window]

You can see the Cucumber scenarios and then watch as the Frank driver automates the application in the iPhone simulator, restarting the application between each scenario.

Anything else?

Frank has additional functionality which I haven't gone into here. There is a javascript web app called Symbiote which is embedded within your iOS app itself. This allows you to interact with your iOS application as it's running, testing UI selection paths and inspecting the application's DOM in realtime. We also provide Cucumber steps for utility tasks such as recording a test run to video (great for debugging a failing acceptance test within a CI system), rotating the simulated device, and restarting the application between scenarios to ensure independent tests.

Where can I get it?

Frank (plus some more documentation) can be found on github right here.

What's coming?

The next important step is including our automated acceptance tests within a Continuous Integration build. We intend to run Frank tests upon every checkin, much as you would run Selenium tests for a web application. A failing test will break the build, emailing the team with a video showing the failing test.

I'm also planning to blog about specific aspects of Frank in greater depth in coming weeks.

Please do check Frank out, and get in touch if you have any feedback, feature requests, bug reports, or anything else!

TDD, Emergent Design, and Punctuated Equilibrium

In my experience good TDD designs tend to have evolved (and hopefully continue to evolve) in a sort of punctuated equilibrium. There are long periods of small incremental changes to a code base, punctuated by infrequent bursts of large design-level refactorings. While the TDD mantra is "Red, Green, Refactor", I think a more accurate version would be "Red, Green, Red, Green, Red, Green, Refactor". Less catchy, I know.

Letting tests drive your design is great, but if you're not careful you will end up with a design which is the result of a simple accreation of functionality. This of course is the reason for the "Refactor" part of RGR. However, in my experience the refactoring part does not occur in a steady flow. Rather there will be periods of time where only small implementation-level refactorings take place during the RGR cycle as new functionality is implemented. Then at some point something will give. Someone may have a design breakthrough, realizing a more expressive/elegant/clean way to express some functionality. Alternatively some niggling annoyance in a subsystem's design will pass the team's tolerance threshold such that they decide they need to clean up the design to remove the annoyance. Both events will lead to a brief flurry of larger design-level refactorings.

A somewhat minor example of the 'niggling annoyance' case would be when someone is adding a 4th optional parameter to a method call and finally decides to bite the bullet and pull all the optional parameters out into a single options hash. An example of the 'design breakthrough' case might be the third time someone adds a subclass in order to specialize some aspect of a base classes functionality. They might realize that really what's going on here is that each subclass represents a Strategy, which can be plugged into the base class. Now both of these examples are rather small-scale, but hopefully they illustrate the concept. It's hard to come up with examples of larger refactorings which are easy to succinctly describe without a bunch of background information.

A key observation here is that principles like YAGNI and 'do the simplest thing that will work' will not work well in isolation. Rather they must live alongside principles like DRY, seperation of concerns, do one thing and do it well, etc. If your sole focus is on doing the minimum amount to get your tests passing you will not end up with a supple code base which is amenable to change. That requires dilligent attention on your part.

Does this mean that TDD leads to bad design? No. TDD does not lead to good design on its own, but it does set the stage for good design to emerge. A team with the safety net of a strong test suite has the courage to follow through and realize these design-level refactorings. A team without that safety net may know exactly what needs to be done but will lack the courage to do so, because they know that any changes will lead to unknown breakages. Thus, the team will be reluctant to undertake these design improvements, as much as they would like to do so.

Finally, this idea of punctuated design equilibrium may sound familiar to folks who've read Eric Evan's Domain Driven Design. He talks about how good teams who are really working to understand a domain will occasionally find themselves up against a breakthrough which requires them to stop forward momentum on features in order to realize a more elegant expression of their core domain. That small section of his really excellent book was certainly in my mind as I started writing this post.

Introducing Noguchi

Generating HTML tables in ruby has always seemed like more of a hassle than it should be. Most of the times that I've had to do it I've been a little frustrated with how, well, ugly the view code looks. So, I decided I'd try and create a nicer way to build tables. The end result is a small table creation library called Noguchi. Given a set of data and some optional configuration it will render a table as HTML or CSV.

Show me!

Here are some quick examples of the kind of things you can do with Noguchi. There are more features than I will show here; for more details check out the README in the library's github repo

Creating a simple table from ActiveRecord model instances

table = Noguchi.table_for(users)
table.render

generates

Name	Age	Sex
Jenny	24	F
Dave	32	M
Hank	27	M

Rendering CSV

table = Noguchi.table_for(users)
table.render_as_csv

generates

name,age,sex
Jenny,24,F
Dave,32,M
Hank,27,M

Rendering collections of hashes

fruits = [
  { :name => 'banana', :color => 'yellow' },
  { :name => 'apple', :color => 'green' },
  { :name => 'orange', :color => 'orange' } 
]
table = Noguchi.table_for(fruits)

generates

name	color
banana	yellow
apple	green
orange	orange

Adding arbitrary custom-rendered columns

table = Noguchi.table_for(users)
table.add_field(:edit)
table.to_render_body_cell_for(:edit) do |context,cell|
  cell.raw_content = link_to( "Edit this user", edit_user_path(context.datum) )
end

generates

Name	Age	Sex	Edit
Jenny	24	F	Edit this user
Dave	32	M	Edit this user
Hank	27	M	Edit this user

The approach

I decided that since the goal of this library was to make table creation code look less ugly I would let the design of the API drive the process. So I started off by thinking about how I'd like table creation code to look like, basically just writing some rough ruby code that used the as-yet-unwritten library to render a basic table. The idea here was to get a simple core API which would render a basic table with very few lines of code, but to make the table rendering customizable by adding various tweaks to that basic table. Once I was happy with how the core API looked I started writing more complex examples, letting that drive out more advanced features in the API. These features were optional configurations which aimed to handle the most common kinds of customization I seem to end up doing to a table. Things like customizing a column header, adding an extra column to contain an edit link, things like that.

Once I had a rough idea of the API in my head, I started writing tests that described the functionality, implementing just enough of the library at each step to make the tests pass. I was plesantly surprised at how well this worked; the entire implementation was driven out by these tests. While I do tend to TDD most of the time, I've seldom done so exclusively. I tend to find myself spending some small amount of time outside of the Red-Green-Refactor loop, usually while exploring a new design approach or a brand new subsystem. I'm quite pleased with how this exclusively TDD approach played out in this case, although I wonder whether it would work quite as well in different circumstances.

Stormcloud will watch over the unicorns.

Hipster geeks crack me up. A nice ancillary benefit of being in this industry is I get to read blog posts about interesting technical stuff which also include phrases such as:

...we developed a new monitoring script, called Stormcloud, to kill Unicorns when they ran out of control...

...Monit would still monitor the master Unicorn process, but Stormcloud would watch over the Unicorns...

...child death during request processing ... would cause that request and all requests queued in the mongrel to send 500 "robot" errors until the mongrel had been restarted...

No need to fear, children. Stormcloud will watch over the unicorns. And if all else fails, a mongrel will send 500 robot errors.

In case you were wondering, the blog post these come from is about Twitter's app server infrastructure.

TickTock: A dirt-simple stopwatch class for actionscript

I just threw together a really straightforward stopwatch class, for use when profiling operations in ActionScript code. You can either use it in an old-skool procedural way:

var tt:TickTock = new TickTock();
tt.start();
doSomeWork();
tt.stop();
trace( "That took "+tickTock.elapsedTimeInMilliseconds+" millisconds" );

or in a fancy-pants, functional, closure-y way:

var tt:TickTock = TickTock.measure( function(){
  doSomeWork();
});
trace( "That took "+tickTock.elapsedTimeInMilliseconds+" millisconds" );

Being primarily a ruby guy, I prefer the fancy-pants approach ;) The class, along with a little sample app, is up on GitHub now.

Why do we estimate effort?

I listened to a really good podcast yesterday on Kanban. One of the topics discussed was the fact that with Kanban estimating story points is optional. Most of my agile experience is with Scrum, so my initial reaction was one of mild disbelief. How can a team perform work without estimating effort! But when you think about it, why do we have this vaguely obsessive focus on story points in Scrum? Surely in other areas there are teams that get by perfectly well without having to determine up-front how much effort each item of work is going to require. What is the value in estimating? Here's what I came up with:

• Tracking velocity
• Deciding on the scope for an iteration
• Prioritizing stories (what will give us the most bang for the buck)
• Release planning

I'm focused on the fine-grained estimations for individual stories here, so I'm just going to skip past the release planning stuff. My rationale being that for release planning you're mainly going to use more course-grained estimates for a whole set of features, rather than estimating every single story. As to the value of story points for priotization purposes, I wonder whether there are many times where the decision is based on how much effort a story would take. Even if that was a factor on occasion, I would argue that the estimation process could be done 'just in time' for the relevant stories in the course of a brief conversation.

Really it seems that the main value in estimating story points is to allow a team to sign up for the appropriate amount of work for an iteration. If a team is using a Kanban approach then this isn't really required. A team can just pull work through until they have enough releasable stories. At any point they can decide to make a release with whatever stories are complete at that time. The restriction of a hard timeboxed iteration just isn't required.

So what are we left with? Tracking velocity. Is that actually useful enough to justify the cost of the estimation effort? I wonder. In my own experience it seems that estimating is a relatively painful part of the agile process. Most engineers just find it hard to do it well.

Hidden benefits?

While reflecting on the estimating and planning sessions I've done with teams in the past, I came up with one very valuable side-effect of the estimation process. In order to estimate well a team will need to discuss in detail what's involved in a story. That can often reveal previously unrecognized dependencies, ambiguous or contradictory requirements, and so on. Perhaps there are other processes that would play a similar role if estimating were not being done? For example if a team is doing feature-driven development then they will probably flush out these kinds of issues as they are defining the acceptance criteria for a story. I've not worked on a team that doesn't do story point estimations, so I'm not sure on this one.

It's interesting to reflect that most of the benefit of estimating effort is done in order to support the agile process itself, rather than the actual creation of software. If a team wasn't doing agile, it wouldn't really need to estimate. In that sense it could be considered waste.

Primitive Obsession obsessions

After seeing the Primitive Obsession code smell crop up in a few different places recently I got to thinking about it in the context of static and dynamic languages.

Essentially this code smell refers to using a primitive data type (int, string, etc), or a cluster thereof, where you could instead be using an explicitly defined type. Probably the most common variant of Primitive Obsession would be a method like:

def is_point_within_bounds( x, y )
# ...
end

I would call this variant Primitives Travelling in a Pack. You'll probably see these two x and y values hanging out together all over the place. Often this variant will be addressed with the Introduce Parameter Object refactoring, leading to something like:

class Point < Struct.new(:x,:y)
end

def is_point_within_bounds( point )
# ...
end

This is a pretty uncontroversial refactoring. It tends to make the code easier to read, and is often the initial stage in the 'budding of' of a full-fledged class (I believe I have the wonderful GOOS book to thank for that term). Once the class is there, it often becomes a locus for a little cluster of methods, often pulled in from surrounding client code. This is a powerful way of letting your design evolve based on needs.

There are other more subtle variants of Primitive Obsession. Some people would say that two methods like:

public class Rental {
  void increaseRentalPeriod( int numWeeks ) {
   //...
  } 

  int getRentalPeriod() {
   //...
  }
} 

would be better refactored to:

public class WeekSpan {
    public int numWeeks;
}

public class Rental {
  void increaseRentalPeriod( WeekSpan period ) {
   //...
  } 

  WeekSpan getRentalPeriod() {
   //...
  }
} 

Applying this refactoring can again be the first step in budding off a new class. However I would say that the main advantage of this refactoring is the explicit typing which it adds when in a statically typed language. Before refactoring there was an implicit typing going on that said "ints in this context actually represent a time period, in weeks". After the refactoring that typing has been made explicit. One outcome of that is that type errors which were previously implicit are now explicit, and will be caught by the type system. Before the refactoring you could have written client code like

someRental.increaseRentalPeriod( numDaysToIncreaseRentalBy() );

and your compiler wouldn't utter a squeak, despite the fact that you're passing in a number of days, rather than the number of weeks which the method expects. With the explicit WeekSpan type, that error wouldn't sneak through.

This explicit typing also helps with future refactoring. If we later decided that it would be better to represent the rental period using a number of days rather than a number of weeks we could use a automated refactoring tool to trivially replace all instances of WeekSpan with DaySpans (or we could just refactor WeekSpan itself into a generic TimePeriod). If we didn't have the explicit WeekSpan class then we'd be reduced to manually searching for all the instances of the primitive int type which happened to actually be representing a time period in weeks.

This is all good stuff, and makes an awful lot of sense in a static language. However, I personally am not convinced that introducing these single-field data types makes as much immediate sense in a dynamically typed language. Both of the typing advantages are lost in a dynamic language. We don't know the type of anything until runtime so we can't check for type violations (however our unit tests help with that), and our refactoring tools can't take advantage of static type information.

The other advantages of introducing these non-primitive types remain, but I would err towards the YAGNI principle. Leave the primitives where they are, and make a mental note that they might need some attention in the future. Once you see a need to move to a next step in the budding off process (e.g. moving a method into the nascent data type), then that's the time to apply the refactoring. Doing so just for the sake of having an explicit type smacks of premature optimization to me.

Postscript

It's interesting to note that some languages (such as Google's Go) allow you to declare an explicit type which simply aliases a primitive. For example in Go you could write

type WeekSpan uint;

This might be the best of both worlds. You get the explicit typing and attendant type safety, without the potential overkill of creating an new single-field class. If you later discovered that budding off a new class was required it would be trivial to refactor that semi-primitive WeekSpan type into a full fledged WeekSpan class.

Encapsulating user interaction events in Flex

When developing the presentation layer in a Flex application I like to follow an MVC/MVP pattern. I also like to keep my views nice and skinny, with as much logic as possible in the controller/presenter. However, I do like to encapsulate some of the details of the UI itself within the view, and so I shy away from exposing raw user interaction events (button clicks, list selections, etc) outside of the view. Instead I like to have the view capture those events and translate them into what I call user action events, which represent higher-level, user-centric interactions. So instead of publishing a 'list item selected' event, the view publishes a 'blog post selected' event. For example, here what a typical event handler would look like in a view's MXML file:

private function onListItemDoubleClick(event:ListEvent):void {
  dispatchEvent( new Event(EVENT_postSelected) );
}

This allows small user experience tweaks (e.g. double clicks to select vs single clicks) without affecting clients of the view. More importantly it helps the view expose a consistent, user-centric level of abstraction - its interface talks in terms of user actions, not UI minutia. A view's controller would register listeners for these user action events via the generic IEventDispatcher::addEventListener(...) exposed by the view, and process them appropriately in the registered listener callback:

public class Controller
{
  //... 

  public function bindToView(view:IView):void {
    _view = view;
    //...
    _view.addEventListener( View.EVENT_postSelected, onPostSelected );
  }
  
  //...

  private function onPostSelected(event:Event):void {
    //... process user action here
    //...
  }
}

One thing to note in passing (we'll come back to it) is the ugly fact that while bindToView(...) is dealing with an abstract interface (IView), it still needs to reference the concrete View implementation in order to get to the View.EVENT_postSelected constant. In real terms the controller class has a dependency on the concrete view implementation.

Back to the story. I want to make sure that my controller processes these user actions correctly, which for me means I need good unit test coverage of the listener callbacks which the controller registers. These callbacks are private methods, so therefore I need some way of simulating the occurrence of these user actions within the unit tests for my controller. Typically when unit testing a controller I arrange for it to be bound to a stub implementation of the view. To simulate these user actions I could have that stub implementation derive from EventDispatcher. During test setup the controller would be bound to the stub view, and as part of that process would subscribe to these user action events. Subsequently my test code could artificially fire the appropriate event within a test case using EventDispatcher::dispatchEvent(...) in order to simulate a given user action occurring.

public class StubView extends EventDispatcher implements IView
{
  // other stub stuff here
}

public class ControllerTests 
{

  [Before]
  public function setUp():void {
    // instantiate controller, instantiate stub view, bind controller to stub view, etc...
  }

  [Test]
  public function doesSomethingWhenPostSelected():void {
    // ... set up test
    simulatePostSelected();
    // ... verify expectations
  }

  // .. other tests

  private function simulatePostSelected():void {
    _stubView.dispatchEvent( new Event( View.EVENT_postSelected ) );
  }
}

This has always felt a little hacky to me, and I started to wonder if that feeling indicated a design flaw (I find that when something feels wrong when writing tests it often points towards a design deficiency). So recently I started experimenting with another approach. Instead of the controller registering event callbacks on the view directly with addEventListener(...), the view exposes methods which do the registration on the controller's behalf. I call these interest registration methods. Instead of the controller calling view.addEventListener( SOME_EVENT_TYPE, my_callback ), it calls view.addUserActionListener( my_callback ).

 // ... in the view MXML
 // ...
 public function addPostSelectedListener(listener:Function):void {
   addEventListener( EVENT_postSelected, listener );
  }

// ... in the controller
// ...
  public function bindToView(view:IView):void {
    _view = view;
  //...
    _view.addPostSelectedListener( onPostSelected );
  }

In production code the view implements these interest registration methods in the same way as the controller did before - by calling addEventListener(...) with the appropriate event type and the callback supplied by the caller. The code is the same, it's just moved from the controller to the view.

The effect this has is quite powerful however. The fact that events are used as the mechanism for invoking the callback is hidden within the view. This becomes interesting when you come to test your controller. Instead of subscribing to events, your stub implementation of the view can implement the interest registration methods by just holding the callback in a instance variable. When the test wants to simulate a user action it can ask the view for the registered callback and call it directly, bypassing the Flex eventing mechanism entirely.

public class StubView implements IView
{
  public var postSelectedListener:Function;
  public function addPostSelectedListener(listener:Function):void {
    postSelectedListener = listener;
  }

   // .. the rest of IView implemented here
}

public class ControllerTests
{
  // ... every thing else as before

  private function simulatePostSelected():void {
    _stubView.postSelectedListener( new Event( 'ignored' ) );
  }
}

What's more interesting is the effect this change has on the interface exposed by the view. Previously we had a view which exposed implementation details - the fact it was handling client callback registration using EventDispatcher), and most tellingly the string constants which identify different event types. We also had different levels of abstraction being exposed in the same interface. Typically the other parts of the view interface worked on the high level of user actions, not on the low level of events being fired of a particular type. With the migration to the interest registration methods we have a consistent level of abstraction, and we can hide all the messy implementation details of the eventing mechanism. Those annoying public event type strings become private and hidden away within the view; an implementation detail. We can even totally encapsulate the fact that the view inherits from EventDispatcher. The explicit interface also feels more typesafe to me. It's impossible to accidentally register for an invalid event code, and it's immediately obvious from the view's interface which user actions it reports.

There are some drawbacks to this approach. Because we're abstracting away the details of the event dispatching mechanism we're also hiding some of the advanced facilities that mechanism provides. For example the approach as described doesn't allow a client of the view to unregister its interest, which would usually be accomplished using IEventDispatcher#removeEventListener(...). I would argue that this is a reasonable price to pay. If that functionality is required in some situations it would be straightforward to add, and because it would be explicitly added as a new method in the view's interface it would be clear that the view was expecting clients to use that method.

All in all I'm very happy with how this experiment turned out. By paying attention to the 'smells' that my tests were exposing I discovered a valid issue with the way different parts of my code interacted. I would argue that changing that interaction to make the tests cleaner does seem to have lead to a cleaner design overall.

Ruby Facets: the mash method

I keep meaning to write up some of the useful gems (if you'll pardon the pun) which are hidden in the super-handy Facets gem. Today I'll cover Enumerable#mash.

Let's say you have a list of Users, and you'd like to create a hash which lets you look up the Users based on their login. You might write something like:

def create_login_hash_for( users )
  user_login_hash = {}
  users.each do |user|
    user_login_hash[user.login] = user
  end
  user_login_hash
end

With Enumerable#mash, you can trim that down to:

def create_login_hash_for( users )
  users.mash do |user|
    [user.login,user]
  end
end

This is much more succinct. More importantly, it expresses the intention more clearly.

Partial commits with git

I've been using git for a few months now. Like all the best dev tools it has slowly permeated my workflow to the point where I'd feel pretty crippled without it. In fact, I don't think I would ever go back to a centralized system like svn at this point. In a pinch I'd fall back to using git locally and then using the appropriate git-to-foo integration to push my local changes from my git repo to whatever the centralized repository was.

So, git is great. However, there's one practice which is common amongst git users which I am still uncomfortable with (even though I do it myself on occasion). I'm referring to the practice of staging some, but not all, of the changes in your working tree to the index, and then committing that partial change set. For example, let's say I've been hacking away on my stamp collector application. I added the ability to 'tag' stamps (folksonomy now being mainstream enough to appeal to your average philatelist). While I was working, I also fixed a couple of badly named methods that I happened to come across during my other changes. With git I can decide to commit these changes separately, through judicious use of the index. I can say 'add changes to files x and y to the index, but leave out z for now', then commit, then add the changes to file z to the index, and then commit that change. If I want to get really fancy I can even add some of the changes to a file to the index, but not all changes. This way I can seperate my changes into two logical commits, one for the feature addition of tagging stamps, and one for the miscellaneous method name cleanup.

This is definitely one of those features that is very cool once you realize the power it offers. It means someone else reviewing my commits will have an easier time, and it even means that I could roll back my feature addition change but still keep the method name cleanup work. Still, I would submit that this can be a Bad Idea.

Why does this concern me? Because any such partial commits haven't been tested before being commited. At this point you might be thinking "Well, don't know about you, but I run my tests before each commit". The point here is that the tests run before you commit are run against your working tree, which in the world of git isn't necessarily the same as your commit. In the Good Old Days of svn, the changeset in your working tree was always the same as the changeset in your commit. With git and the index (aka the stage, aka the cache, don't get me started on that) that's not the case. Your working tree may contain changes to files x, y and z, but you've decided to only commit the changes to files x and y. Or even more extreme, you've decided to commit the changes to file x but only some of the changes to file y (maybe the other changes where related to your method renaming binge). So you're running your tests against one set of code (your working tree, with changes to x, y, and z), but your commit is another set of code. I think that ninety nine times out of a hundred this distinction won't matter. Your "technically untested" commit would still have passed the tests anyway. Plus, what you're almost certainly following it up straight away with another commit which will be the same as your working tree. What are the chances that someone will manage to stumble upon an invalid state like that. Probably really low. But still, kinda scary I think. It seems a bit like saying "well, this race condition is really unlikely to happen, right...". I'd rather not have to even think about that. Another thing to consider is the 'cool' use case that someone could decide to revert one commit but not the other.At that point you have code sitting on head that hasn't been tested.

One solution to this would be to ban the use of commits that don't include all changes in the working tree. Yeah, right. Not likely, and not helpful. Staging is definitely a useful way to add more structure to your change history, and not something I'd like to leave behind.

I wonder if a better solution could be achieved with the judicious use of commit hooks. What if we had a pre-commit script that would take the change set that was about to be committed (NOT whatever is in the working tree) and run tests against that tree. If the tests fail the commit fails. Now we would be left in a place of greater confidence than before. We wouldn't even need the discipline to run the tests by hand, because even if we forgot then git would be running them for us anyway. To be honest I'm not sure of the feasibility of creating this kind of setup. I'd love to find out more about how feasible it would be.

Option number 3 would be to have a CI pipeline such that you don't ever commit changes to a branch that others can touch until the CI system has had a chance to run tests against your commit. Instead, you would always be commiting changes to a private branch. The CI system would detect your commit, run a build, and then merge your changes into a shared branch if and only if your commit passed muster. I don't think this would prevent commits in the middle of a batch of commits being pushed to your private branch from bein un-tested, but it would prevent the system ever getting into a state where the shared head is untested. This is an idea I'm planning to blog about more at some point in the future.

In conclusion, while I find myself sometimes taking advantage of this powerful feature of git, I always feel a little nervous doing so, and try and take extra care.

an inverted include? for ruby

I've always found it a slightly hard to read ruby which uses Enumerable#include?(), especially when the Enumerable your testing against is a literal or a constant. For example, let's say you're checking an input parameter to guard against invalid input. You might write something like:

unless VALID_COMMANDS.include?( command_param )
  whine_to_user()
  return
end

This makes sense, but it seems backwards to me. I don't care whether some array has a value in it so much as I care whether a value is in some array. Obviously that's just two ways of saying the same thing, but the latter seems to capture the intent much more to me. I think it would be easier to understand this:

unless command_param.in?( VALID_COMMANDS )
  whine_to_user()
  return
end

This evening it (finally) dawned on me that this would be ridiculously trivial to implement:

class Object
  def in?( enumerable )
    enumerable.include?(self)
  end
end

In fact, this was such a trivial fix that I'm now left wondering (a) whether this is already in ActiveSupport or Facets or whatever and I just haven't found it yet and (b) whether there's some huge flaw in this that I'm not spotting...

Flex Patterns: Presentation Adapter

Encapsulate the logic for presenting a domain object, and provide an object for skinny views to perform data-binding against.

Problem

When using Presentation Model our goal is to bind UI elements in your Skinny View directly to individual components of the Presentation Model. This requires translating information in Domain Model instances into a presentation-specific form. At the same time we need to be able to map back from that presentation-specific form to the underlying domain model instance in order to present user interactions in terms of our domain model.

Context

We are developing a UI component in a Flex application using some form of MVC/MVP. This UI component will be displaying information about a domain object, e.g. a list of Users. We are using the Presentation Model pattern or similar, so we want Skinny Views.

Forces

• We need to transform information from a Domain Model class into something suitable for display
• We want to keep formatting logic out of the view, using Flex databinding from view controls to a Presentation Model
• We want to keep formatting logic out of the Domain Model, because it's presentation-specific, and not the responsibility of the domain model.
• Clients of our UI component expect to interact with it using instances of the Domain Model class. For example, clients should be able to pass in a list of Domain Model instances to display, and the UI component should publish events which refer to Domain Model instances.

Solution

We can use a Presentation Adapter (PA) to wrap a domain object (an instance of a Domain Model class). The PA provides a presentation-specific formatting of some or all of the information represented by that domain object. The PA also exposes a reference to the domain object itself. This allows UI component code to map from the PA back to the domain object is represents when reporting user interactions back out to clients of the UI component.

Example

Let's say we are creating a Post Listing component which lists a collection of blog posts, and allows the user to select specific posts from that list. Our Presentation Model needs to include a collection of posts to list, and our View will contain some kind of list control which will be bound directly to that collection of posts. We want each post to be listed in the UI using a specific format, which will include the post title and the number of comments associated with the post. The application's Domain Model contains a BlogPost class, and our component is expected to expose an interface which talks in terms with BlogPost instances. The client of the Post Listing component will supply a collection of BlogPost instances which it wishes to be displayed in the list. When a user selects a post the component's client expects to receive a 'post selected' event which includes the BlogPost instance that was selected by the user. In other words, the client does not need to know anything about the Presentation Adapter we will be using.

We'll create a PostPA class which will act as a Presentation Adapter for the listing. It will expose a label field. The Presentation Model can hold a list of these PostPAs (one for each BlogPost supplied to the Post Listing component), and the View's list control can be bound directly to that list of PostPA instances.

We also need some simple formatting logic which transforms a BlogPost instance into the appropriately formatted string which will eventually be shown in the list control. That formatting logic should live within the Post Listing component, as it's presentation-specific. In fact it's likely that the formatting is specific to this particular UI component. The Presentation Adapter is a good place to put this formatting logic (although there are alternatives which I'll see below in the Variants section).

public class PostPA
{
 private var _post:BlogPost;
 
 public function PostPA( post:BlogPost )
 {
  _post = post;
 }
 
 public function get label():String
 {
  return _post.title + " ["+ post.comments.length+" comments]";
 }
 
 public function get post():Post
 {
  return _post;
 }

}

We also need to map from BlogPost instances to PostPA instances, and vice versa. We'll put that logic in our Presentation Model. core UI logic can supply the Presentation Model with a collection of BlogPost instances, and the view will be updated with a list of corresponding PostPA instances.

public class Model extends EventDispatcher
{
 function Model(){
  _postPAs = [];
  _selectedPostIndex = -1;
 }
 
 private var _selectedPostIndex:int;
 private var _postPAs:Array;
 
 public function get selectedPost():Post
 {
  if( _selectedPostIndex < 0 )
   return null;
  else
   return _postPAs[_selectedPostIndex].post;
 }
 
 public function set selectedPostIndex(index:int):void
 {
  _selectedPostIndex = index;
 }
   
 public function set posts(posts:Array):void
 {
  _selectedPostIndex = -1;
  _postPAs = posts.map( function( post:Post, i:int, a:Array ):PostPA {
   return new PostPA(post);
  });
  dispatchEvent(new Event("postPAsChange"));
 } 
 
 public function get posts():Array
 {
  return _postPAs.map( function( postPA:PostPA, i:int, a:Array ):Post {
   return postPA.post;
  });
 }
 
 [Bindable (event="postPAsChange")]
 public function get postPAs():Array{ return _postPAs; }
 
}

Our Post Listing component needs to send an event whenever a user selects a post, and that event needs to reference the BlogPost instance that was selected. To that end, the Presentation Model also exposes methods which allow the view to update the selected post based just on a list index, while the core UI logic can ask for the underlying BlogPost instance which was selected. Now, when the list control sends an event saying an item has been selected the View can update the Presentation Model appropriately and then signal the core UI logic. That logic can then ask the Presentation Model for the selected BlogPost, and dispatch a 'post selected' event, including that BlogPost instance in the event.

Variants

The decision on where and when the presentation formatting logic is done defines several variants on this pattern.

Dynamic Presentation Adapter

Presentation formatting logic lives in the PA class, and the formatting is performed on-the-fly as the view requires it.

Static Presentation Adapter

Presentation formatting logic still lives in the PA class, but the formatting is done at construction time. Depending on usage patterns this could be more or less performant than the Dynamic Presentation Adapter variant.

Dumb Presentation Adapter

Presentation formatting logic lives within the Presentation Model which is creating the Presentation Adapter. In this case the Presentation Adapter itself becomes a simple value object with no logic, or even just a dynamically created object.

Related Patterns

Generally a Presentation Adapter will be used in the context of a Presentation Model, where the Presentation Model contains instances of one or more Presentation Adapters (collections or otherwise). A Presentation Adapter is a specific form of the GoF's Adapter Pattern.

Alternative Patterns

Instead of a Presentation Adapter one could use a Transformer/Mapper, where a single Mapper instance performs the presentation-specific formatting for a whole class of domain objects. This Mapper is attached to the UI control as part of the binding mechanism, and does the formatting on the fly. The Mapper could be a simple Function, or an instance of a specialized Mapper class.