Monkey-patching is extending or modifying the behavior of code at runtime without changing its original source code. You can monkey-patch any code, it doesn’t matter whether it’s your own code or not. This is distinctly different than traditional sub-classing because you are not creating a new class, instead, you are reopening an existing class and changing its behavior.

Monkey-patching is possible in Objective-C by using categories. In fact, the definition of a category practically matches that of monkey-patching:

"A category allows you to add methods to an existing class—even to one for which you do not have the source."

In this series of posts, we’ll use categories to add and change methods, to add new instance variables and properties, and introduce swizzling, a technique that allows us to extend and preserve existing functionality. TL;DR »

Category Basics

To modify an existing class specify the category in both its interface and implementation definitions:

Interface Definition

Implementation

Adding Simple Methods

The most basic usage of categories is to add a new method to an existing class.

Suppose in our application we want to output dates relative to the current time, e.g., “13 minutes ago”, “4 hours ago”, “just now”, etc. Traditional object-oriented solutions would have us introducing a new class that either extends NSDate (e.g., creating a RelativeDescriptionDate subclass with a timeAgoInWords instance method) or is a standalone helper/utility class (e.g., [NSDateHelper timeAgoInWordsFromDate:myDate]).

But with categories, we can reopen the NSDate class and simply add a new instance method:

NSDate+Formatting.h

NSDate+Formatting.m

Now every NSDate object will have the new method available to it. The following code:

Will print out the following on the console:

The Dangers of Simply Overriding Methods

We can take this a step further and instead of adding new behavior we’ll override existing behavior. Continuing with our example, what if we wanted the default description of a NSDate object to include the time ago in words? We could simply do the following:

However, this is strongly discouraged for two reasons.

1. Other frameworks may rely on the expected behavior of the original method. We now have to go through the trouble of re-implementing that behavior, in addition to the new functionality we wanted to introduce, or risk strange side effects and possibly even crashing out.
2. If multiple categories implement the same method, the last one loaded wins! The load order is consistent within an application, but it’s arbitrary, out of our hands, and fragile. For all we know, our implementation could itself be overwritten by an internal framework category!

Because of these reasons, this blunt approach to overriding methods should only be used for the simplest of cases. Later in this series, we’ll explore how swizzling allows us to override a method while preserving all implementations.

Including Your Monkey-Patches

Categories are not automatically “picked up” in a project. Any code that relies on the behavior will need to #import the necessary header files:

However, including the same set of headers over and over again is redundant. We should first create a single header file that imports all of our most frequently used categories:

We can then import this single header file into a prefix header that is added to all source files. XCode projects often have a .pch file in the Supporting Files group for this very purpose.

Next Up

While adding and overriding classes is straightforward, there is one very big caveat when using Categories; you cannot add new instance variables to a class. We’ll take a look at working around this limitation in the next post.

tl;dr

• Use Objective-C categories to add functionality to existing classes without subclassing.
• Avoid simple overrides with categories as it can cause problems with other frameworks.
• Use prefix headers to easily import your extensions.

I've been working on a post here for C5 and in order to make my points, I was referencing gists hosted by GitHub. When those gists were shown as embeds, the line numbers, and thus the clarity of my documentation, was lost. We use Markdown for the creation of the texts so I needed something I could write inside of a Markdown post that would be applied as CSS.

Thanks to these tips:

1. http://www.whyhat.com/2012/01/line-numbers-on-embedded-gists
2. http://stackoverflow.com/questions/524696/how-to-create-a-style-tag-with-javascript

I was able to come up with the following:

Designing with services and a service layer is popular in the Java J2EE/Spring community. However, it’s not common in the Rails world. Is this because of the Ruby community’s general backlash against the complexity of Java? Or has the rise of HTTP-based JSON APIs made this architecture obsolete? To answer these questions, let’s take a deeper look at services and the benefits of a service layer.

What is a Service?

In Domain-Driven Design, Evans defines a service as an operation offered as an interface that stands alone in the model. In other words, a service is an action, not a thing. And instead of forcing the operation into an existing object, we should encapsulate it in a separate, stateless service.

It’s not always clear what logic constitutes a service. Taken to the extreme, domain models could be stripped entirely of their domain logic, and turned into nothing but simple data structures (an AnemicDomainModel). A good heuristic is to look for large, domain objects doing too much work and try to break their multiple responsibilities into separate services. At other times it may be your own intuition telling you that some logic just doesn’t feel to be in the right place. To get started, it’s helpful to classify services into different types.

Types of Services

Evans defines three types of services:

• Application
• Domain
• Infrastructure

Application Services

An application service is a service that provides non-infrastructure related operations that wouldn’t come up when discussing the domain model outside the context of software, i.e., in its natural environment.

Exporting account transactions as a CSV file in a banking app is an example of an application service because a file format, CSV, has no meaning in the domain of banking.

Application services improve the cohesiveness of your domain model by preventing “software” implementation details from leaking into it.

Domain Services

A domain service scripts a use-case involving multiple domain objects. Forcing this logic into a domain object is awkward because these use-cases often involve rules outside the responsibility of any single object.

Continuing with the banking app, a funds transfer would be an example of a domain service. Transferring funds doesn’t quite fit in either of the involved account objects, or perhaps a customer object, so it becomes a standalone service.

An alternative implementation, could be an instance method on Account, taking the amount and destination account as parameters. However, transferring money between accounts feels like the responsibility of another object, not a core responsibility of an account. Domain services like this one really help maintain the core responsibilities of your domain objects.

Another example of a domain service is a sitewide search across multiple domain models. Since it searches across multiple domain models it doesn’t conceptually fit in any one particular model. Instead, it should live in a separate search service.

Simple CRUD operations are not domain services. For example, I would consider the following an anti-pattern:

Sure, this does make the UserController independent of the domain model, but this type of flexibility is premature. Instead, the controller should interact directly with the domain model when creating a new User. Domain services should be short scripts, not simple 1-liners that delegate to an almost identical domain model interface.

Infrastructure Services

An infrastructure service encapsulates access to an external system. Infrastructure services are often used by application and domain services.

E-mailing and message queuing are two examples of infrastructure logic that has no place in a domain model.

Infrastructure services make your domain model more reusable by separating out non-domain, “software” concerns.

What is a Service Layer?

In PoEAA, Stafford defines a service layer as an application’s boundary and set of available operations from the perspective of interfacing client layers. In other words, it’s your application’s API.

Let’s take a look at some of the benefits of a service layer to see if they are useful in the Rails world.

Supporting Multiple Clients

In most web apps, the API mainly consists of simple CRUD use-cases. Encapsulating your application’s API, allows it to be reused across multiple client controllers, for example, an HTML and a Thrift client. The resulting controllers are thinner, and more cohesive.

I see this reuse across multiple clients as less and less of a benefit because of the popularity of HTTP-based JSON APIs. Most apps will typically have an HTML client and a few additional clients, for example, an iPhone and a console app, but the same controllers will serve both HTML and JSON. In a way, the controllers have become the services because all clients talk to the app over HTTP.

This reuse was more valuable when you could have non-HTTP based clients, for example, an Adobe Flash app using Hessian.

Encapsulating Application Logic

Stafford separates business logic into domain and application logic. Domain logic being purely the problem domain. Application logic dealing with technical responsibilities, for example, coordinating a workflow or sending an email.

In order to build a more cohesive and reusable domain model, application logic should be handled by infrastructure services, possibly in a service layer. Putting application logic into a domain model that’s used by multiple clients may have unwanted side effects. For example, if you want HTML clients to be emailed after user registration but don’t want your JSON API clients to be notified at all. So instead of emailing users from the domain model…

…let your controller ask a service to do it.

The Rails community definitely has gone back and forth on where to put application logic. Creating a service layer for it is too much though. Instead, put it the appropriate respond_to block in your controllers.

Applying Cross-Cutting Concerns

Java web apps using the Spring Framework, commonly use services to apply cross-cutting concerns, for example, transaction management and security.

Transaction management is a common justification for a service layer, specifically transaction management spanning multiple transactional resources. For example, in the Spring Framework, it’s possible to atomically write to a database, send an email, and enqueue a message.

In a Rails app, ActiveRecord provides automatic, and if necessary manual, transaction management. I can’t say I’ve ever thought much about transaction management across multiple transactional resources, but I see no reason for it not to belong in a controller. I’m not entirely sure why Spring discouraged transaction management at the controller level. Maybe for easier testing.

When Should I Use A Service Layer

The only reason to use a service layer is if you have to support multiple clients using different protocols. HTTP and JSON have become the de facto client communication protocol and format, eliminating the need for a service layer. The additional indirection and flexibility of a service layer should only be considered when you have to add a client that doesn’t speak HTTP. However, it’s still beneficial to use Evans-like services from your controllers in order to encapsulate domain, application, and infrastructure logic and preserve the cohesiveness of your domain model. Always remember to only build for today, not what could happen tomorrow.

While it wasn’t as trivial as a traditional server-side implementation in Rails, it did turn out relatively clean. This is a long post, and if you make it through it, let me know what you think.

Server-side Setup

Our server-side is a stock Rails 3.1 app. We’ll go with a classic blog app consisting of a single Post model to CRUD.

We’ll use the backbone-on-rails Ruby gem to add backbone.js and underscore.js (backbone.js’s only dependency) to our Rails app.

The backbone.js and underscore.js files are not copied into your Rails app’s directory. They’re both automatically loaded by the backbone-on-rails gem (the jquery-rails Ruby includes jquery.js and jquery_ujs.js the same way).

Let’s use the scaffold generator from backbone-on-rails to generate our client-side Backbone.js objects.

We’ll be using CoffeeScript, the Rails default client-side language, throughout our Backbone app. CoffeeScript’s cleaner, Ruby-like syntax will help make the code more readable and understandable.

Listing Posts

We’ll start our app by implementing a “Read” action, the homepage. The homepage will be a list of all our posts. The backbone-on-rails scaffold generator has already created for us a router, an index view and template, a collection, and a model. To wire up the homepage we’ll need to modify our router.

Backbone routers are like controllers in Rails. They map routes to actions. The empty route represents the default action, in our case, the homepage.

app/assets/javascripts/routers/posts_router.js.coffee

In our index action, we create a Posts collection, a view for the collection, and then tell the collection to fetch its posts from the server. We don’t tell the view to render itself because the fetch is asynchronous. We’ll see later how the view uses an event handler to render itself after the fetch.

The Posts collection is configured to make server-side requests to our Rails app at “/posts” and to contain Post models.

app/assets/javascripts/collections/posts.js.coffee

Our Post model is as simple as it gets. It’s just a Backbone.Model subclass and contains no custom logic.

app/assets/javascripts/models/post.js.coffee

Before we take a look at the PostsIndex view, let’s first quickly go over the Rails layout used on the server-side.

app/views/layouts/application.html.erb

The only change we’ve made to this default Rails layout is the addition of a single “#app” <div>. This <div> will act as the container for our app. Each Backbone view will replace its contents.

Now we can take a look at the Backbone view.

app/assets/javascripts/views/posts/posts_index.js.coffee

On initialization, the view binds its render method as a handler to its collection’s reset event (this is the Posts collection we created in the Blog.Routers.Posts#index action). The Posts collection will trigger a reset event after successfully fetching its posts from the server. When the event is fired, the view will render its template and create and render another view for each Post in its collection.

Here’s the template used by the PostsIndex view:

app/assets/templates/posts/index.jst.eco

This table will be populated by the view used for each post in the collection:

app/assets/javascripts/views/posts/posts_item.js.coffee

And its template:

app/assets/templates/posts/item.jst.eco

There’s one last thing we need to do before we can view our homepage in a browser: we have to bootstrap our app’s router.

app/assets/javascripts/blog.js.coffee

An onDOMReady event handler invokes an init function that creates a PostsRouter and tells Backbone to start monitoring all hashchange events. All our client-side pages will use hash fragments as URLs. Backbone will listen for hash fragment changes and route them using the routes specified in our PostsRouter.

Finally we can now start our Rails server and hit our app at http://localhost:3000/posts. Unfortunately, we don’t have any posts yet. So let’s move on to creating a post.

Creating a Post

At the bottom of our existing home template is a link to create a new post:

app/assets/templates/posts/index.jst.eco

This means we need to add another route and action to our PostsRouter.

app/assets/javascripts/routers/posts_router.js.coffee

In our new action, we create a Post model, then create a Posts collection and bind an anonymous handler to its add event. A collection will fire an add event whenever a new model is added to it. Our add event handler performs the equivalent of a server-side redirect by navigating the router to the “empty” router (the homepage). Finally we create and render a view to submit a new post.

app/assets/javascripts/views/posts/posts_new.js.coffee

The element (PostsNew#el) used in our new post view is the global “#app” <div>. The new post view will replace the contents of this <div> with its own template containing a form to submit a new post.

The view also registers a handler to the submit event from the <form> in its template. This handler stops the default form submission behavior and then asks its posts collection to create a new post. This will result in an HTTP POST request to the server and, if successful, the collection will fire an add event. This is the same event our PostsRouter, in its new action, bound an anonymous “redirect” handler to.

And here is the new post view’s template:

app/assets/templates/posts/new.jst.eco

Great, we can now create posts. However, we can’t let people create posts without a title and a body. Let’s see what we can do to validate our new posts.

Validating a Post

Adding some client-side validation will help improve the responsiveness of our UI. We’ll still validate posts on the server-side, but for the user’s sake, I feel this duplication is worth the tradeoff.

Backbone models include a validate method that can be used to perform custom validations. However, as Rails developers we’re used to ActiveRecord‘s high-level, declarative approach to validation. And thanks to the jQuery validation plugin, we can have declarative validation on the client-side too.

First, download the plugin (after downloading and unzipping it, remember to restart your Rails server).

Next, add the plugin to our application’s JavaScript manifest file.

app/assets/javascripts/application.js

Now we can add some validation to our new posts.

app/assets/javascripts/views/posts/posts_new.js.coffee

The jQuery validate plugin allows you to specify per-attribute validation rules. Here we’re requiring a title and a body. The validate method will stop the form submission when validation fails. This will also prevent the new post view’s form submission handler, #create, from executing as well.

Go and give it a try in the browser. Submitting a post without a title and body will now fail and display an error message(s).

Viewing a Post

Ok, so far we can display a list of posts, create a post, and validate a post. Next up is: viewing an individual post.

On our home page, each post row included the following link for viewing the post:

app/assets/templates/posts/item.jst.eco

Let’s add a route and action to our router for this post page (i.e., #show).

app/assets/javascripts/routers/posts_router.js.coffee

This newest route includes a named parameter, :id. Backbone will automatically pass the named parameter’s value as an argument to our #show action.

Currently in Backbone, fetching an individual model isn’t very elegant. Above is one of the cleanest ways. You first create a model with the requested id, then add the model to a collection, and finally, tell the model to fetch itself.

Our #show action also creates an instance of the following PostsShow view for the individual post.

app/assets/javascripts/views/posts/posts_show.js.coffee

During initialization, the view adds a handler to its Post‘s change event. The Post will fire a change event after it has been successfully fetched.

The element (PostsShow#el) for this view is the same global “#app” <div> container that was used by the post list and new post views. And like those two views, an individual post view will also replace the contents of this <div>.

And here’s the posts show view’s template:

app/assets/templates/posts/show.jst.eco

The “back” link goes back to our homepage.

Client-side MVC

Backbone.js brings the power and maintainability of MVC to the client-side. Routers can be used like Rails server-side controllers to create responsive, single-page apps. Views are also like controllers, but instead of responding to url changes, they respond to DOM level events, such as link clicks and form submissions. Templates contain the app’s markup, they’re what Rails calls views. Models and collections round out Backbone.js, providing traditional class-based, client-side domain modeling.

We’ve only covered the first two letters in CRUD, but it was a lot! I hope this article can give you some direction in implementing the rest of them. The client-side JavaScript MVC space is growing rapidly. Backbone’s quick and easy Rails integration makes it an easy sell but there are other options. Be sure to research other frameworks before evaluating what works best for you.

In this case, I wanted to use the nifty wkhtmltopdf utility to create a PDF. I was able to call the binary just fine with Homebrew on OSX but found that I had to use a custom binary checked into git for our production environment on Heroku. So I created a configuration variable to store where wkhtmltopdf could be found in the current environment.

First, we define a default value for all environments in config/application.rb:

module Configurator
  class Application < Rails::Application
    # By default, let OSX resolve the path to the binary
    config.wkhtmltopdf = "wkhtmltopdf"
  end
end

Then we override the default setting as necessary in config/environments/:

Configurator::Application.configure do
  # Settings specified here will take precedence over those in config/application.rb

  # Point Heroku explicitly to the binary we need to use
  config.wkhtmltopdf = "#{Rails.root}/bin/wkhtmltopdf"
end

Lastly, we access the configuration element in our code:

  cmd = [Configurator::Application.config.wkhtmltopdf, url, tmpfile.path]

Yes, that’s it. Just use Rails’s environment support and config to store your own configuration elements. They’re trivial to set, trivial to access and require no third-party gems or custom text files.

How does Agile help us to do better work for our clients?

To answer that question, I think it’s important to reflect on what makes building a product hard. Here’s a clue: Everything.

There are technical challenges, but those are the least of your worries in practically every case (especially early on). There are product questions: who are you building for? what features do your customers really want? how can we validate our hunches in a meaningful way? what incarnation of those features will be both useful and a delight to use? There’s time pressure. And to add fuel to the fire, the team is made of people. You know… with ideas, egos, personalities and feelings. It’s amazing successful products happen, period.

We wanted a process that’s effortless when it’s working awesome while also giving us signals when something is broken. We’re not interested in process just for process’s sake. It turns out that Agile can help navigate these challenges and gives us pretty clear warning signals.

At the Core

In trying to distill out the most important parts of our Agile process, I came up with my take on the essential ingredients. I’m not saying other aspects aren’t important too, just that these make a strong foundation.

• Small units of work
• Optimize for value
• Iteration
• Product owner involvement
• Feedback
• Honesty and trust

If any one of these is missing or broken, the project has a much higher risk of running into trouble. That doesn’t necessarily mean complete failure, but it does mean the project and overall experience will fall short of its potential.

Small units of work keep the team focused and allow for greater flexibility when planning. We write user stories and every one of them captures single workflow framed from the user’s perspective. A story should be whole, meaning it delivers value to the user on its own. Stories normally take a couple of minutes to a couple of days to deliver. When they’re small it’s easy to move them around and make tactical decisions during planning. It’s also easier to avoid needless yak-shaving when the stories are small.

Small units of work aren’t enough, they must deliver Value. We typically measure value in terms of user-facing functionality. We know that some amount of infrastructure, architecture, meetings, etc needs to happen to build a product. However, that’s not what first draws a customer to a product. It has to solve a customer’s problem. Getting everyone on the same page about value is crucial, otherwise folks may be optimizing for different things.

Software products evolve over time through the addition of new features, the enhancement of existing features, and removal of unused features. It’s inherently Iterative. We start the process of iteration from week one. By the time a product sees its first ray of light, the team has executed the process of planning, designing, building, and deploying many times. The structure of the process is in place and the team has enough experience with it that it can be repeated confidently.

Knowing that there’s always an opportunity to iterate on a feature allows us to build the right-sized version of the feature for where we are in the lifecycle of the product. Not every feature needs to have all of the bells and whistles when it’s born. The time saved can be spent on something that is more valuable.

Every one of our projects has a Product Owner who’s part of the client team. Our goal is to guide and empower the product owner so that they can direct the team’s focus on what’s important. Some product owners are very involved and others minimally so. The low bar of involvement includes two important activities: prioritization of stories and acceptance of the stories once they’re complete. Without these, there’s no one at the helm and the chance that the client isn’t going to be happy with the engagement goes up a ton.

There’s internal and external Feedback. External feedback on the product can be collected via a wide array of techniques. Until ideas are validated by customers, they’re just assumptions. Building features on top of untested assumptions drives up the chance that we’re building a dud. It might be high-quality code with an extensive set of automated tests, but who cares if no one wants to use it. Building a product without integrating external feedback is like betting everything on your first hand of poker when you haven’t yet learned the rules.

Internal feedback comes from the team and improves the process itself. Reflecting on how it’s going and making changes to better suit the reality on the ground is critical to keeping the process a good fit throughout the lifetime of the product. Otherwise, the process starts getting in the way when things are going awesome or it starts failing to give signals when it should.

It should go without saying: Transparency and trust are key to building a team that can overcome the challenges of building a product. If there’s bad news, we want to deliver it early so that we’re in the best position to do something about it and reap the benefits. Without trust, it’s hard to stay psyched about the people with whom you’re working. When every action comes from a place of honesty and your intentions true, trust grows naturally.

Signals

Here are a couple of the common signals that suggest something’s up:

Low velocity – Velocity is the rate at which the team is completing stories that deliver user-facing value. Really low velocity can be a sign that stories are too big, there are inefficiencies in how work gets done, or the team is spending a lot of time on “infrastructure”.

Erratic velocity – Often the result of inconsistent planning. When the backlog is well thought out, things move fast. When the team gets to stories that are poorly written or vetted, productivity grinds to a halt.

Slow acceptance – The product owner isn’t providing the team with the feedback it needs to know it’s doing a good job. Sure, developers move on to the next story, but they may be building on building blocks that miss the mark. It can be a real drag on morale and velocity.

Big bug fix session before a release - Rather than finding and fixing bugs continuously, the team is delivering stories that are buggy. That debt has to be paid down before the software gets into the hands of users. This creates a false sense of velocity which is knocked down periodically before a release.

Others: Running out of stories, stories are frequently blocked, need for big refactors.

The more experience you have the easier it is to pick up on the signals and figure out what to do about them.

What about the Developer Practices?

I’m leaving developer practices out of this conversation deliberately. Testing, continuous integration, pairing, sustained schedule, etc are all second nature for us. There’s enough content there for a another article (or several).

Conclusion

My experience has shown that if the process includes the above components, we’re able to rapidly build valuable features. When something isn’t right and we’re being perceptive, it becomes apparent quickly and we’re able to reflect and make the changes necessary to fix the problem. In the end, Agile lets us welcome feedback that inspires course correction while also making it really hard to overlook issues when they come up.

Our talk is going to cover product design, process and technology. We want to share the whole experience of building a product, not just the technical details.

Product Design Topics

• Design and development process
• Usability testing
• Prioritizing features to match a budget

Technical Topics

• Overview of the architecture and technical stack (node.js, express, jade, socket.io, flash, etc)
• Using development spikes to reduce technical risk
• Testing node.js
• Lessons learned

After our talk we’ll turn it around and open the floor for those in attendance to share their relevant experience, in 5-10 minute mini-talks.

Additional details and RSVP: http://c5-the-ovee-story.eventbrite.com/

The good folks at Instagram posted a fun challenge on their engineering blog recently:

"Your challenge, if you choose to accept it, is to write a simple script that takes a shredded image in as input and outputs an unshredded and reconstituted image. That is, imagine if you took an image, divided it into an even number of columns and shuffled those columns randomly to produce a shredded image. Then, take that image into the script and output the original image."

(The original post is here: Instagram Engineering Challenge: The Unshredder).

This struck me as a great opportunity to hack out some code in Go (rev 60.1) as part of my continuing exploration of the language and its packages.

The problem

Here are the input and target output images:

The shredded version

The unshredded version

They offer the following tips:

1. Don’t overthink it. Use of really complex algorithms isn’t needed. Our solution WITH the bonus exercise comes in at just over 150 lines of python.
2. Think about how you would quantify whether or not two shreds ‘fit’ together by using pixel data
3. Assume you’re using the source image, or other normal photographs without edge-case patterns.
4. There are edge cases where the script we wrote with our approach will not work because of repeating patterns. This is OK in your script as well. Don’t worry about special cases – focus on making the sample images work that we’ve provided.

Great. The simplest approach that occurred to me was this:

1. Assume the left-most shred is in the right place.
2. Search the other shreds, find the one that fits best to the right of the first one, then stick it there.
3. Repeat until you run out of shreds.
4. Figure which shred is actually the left-most one, then reorder to that configuration by rotating the ring of shreds.

As it turns out, this works. My solution is on Github here: https://github.com/joncooper/instashred. They've run out of t-shirts, though , so no soup for me.

Here's a quick tour of the standard library's packages that I used:

image

The image.Image interface from the image package provides what the docs describe in their typically awesome and laconic manner as "a finite rectangular grid of Colors drawn from a ColorModel."

Basically, the image.Image interface defines a read-only grid of pixels expressed as image.Color, upon which you can call RGBA() to get out a tuple containing alpha-premultiplied channel intensities.

At first the read-only nature of image.Image made me scratch my head a bit. But it ends up being pretty neat. You can do things like create a procedural image which can then be sampled, like this:

The standard library also implements image.Tiled, which acts like an infinitely (okay, just extremely large) large tiling of a source image. See the source here--it's just pretty.

image/png

Image file support is minimal but useful at the moment. There are image subpackages that implement decoding/encoding for JPEG and PNG, and decode only for BMP, GIF and TIFF.

Here's an example for how you write an image.Image to a PNG file:

image/draw

This package implements image compositing functions and little else. In particular, it doesn't implement vector art staples like line, circle, rectangle, etc.

It's deals solely with compositing images by copying image.Color pixels from one image.Image and pasting them into a draw.Image, optionally using a mask and a Porter-Duff compositing operator.

See the golang blog's post on this package here: The Go image/draw package.

The primary operation I used is image.Draw, which has the following function signature:

func Draw(dst Image, r image.Rectangle, src image.Image, sp image.Point, op Op)

This copies a region the size of r from src into dst with the top left corner at sp.

Here's an example combining tying the last three together:

An aside on Go interfaces

The relationship between image.Image and draw.Image is extremely representative of idiomatic Go. In Go, a type doesn't declare that it implements an interface, it just does so, and it gets checked statically at compile time.

A draw.Image is just like an image.Image, but you can draw into it. The interface requirements are a superset of those defined in image.Image. Taking a look at the source to draw.Image reveals the neat way that interface inheritance happens in Go:

Wrap

This implementation was enjoyable; I am really warming up to Go.

So far, the standard libraries are uniformly sensible and in many cases beautiful. It's clearly an opinionated language and set of packages, but so far, I seem to agree with those opinions.

Cheers,
Jon

This blog post is not about that.

I started to write up a post about the Chrome extension and how I developed it (forthcoming), but realized that I needed to show screenshots. Unfortunately, I can’t use images of a client’s production tracker. Hmm.

I quickly whacked together a Ruby script to generate realistic-looking stories in a tracker project. Here it is!

github: Lorem Tracker

A populated tracker looks like this:

This might be a useful starting point if you need to

• Teach a friend, client or coworkers how to use tracker without touching production data
• Import a bunch of stories that you wrote in a text file
• Dump a bunch of stories for analysis in Excel

I use Justin Smestad‘s lovely gem, pivotal-tracker. This gem provides an ActiveRecord-ish wrapper around the Pivotal Tracker API.

Adding a story using his gem is as easy as:

Also check out the pivotal-tracker gem’s API docs for more details on how to use it. Anyway, here’s the source, if you’re interested:

Cheers,
Jon

For months, web_steps.rb contained a warning of its negative effects on feature maintenance. Like most developers, I ignored the warning. During a recent upgrade of an existing Rails app, I realized it was now gone. Instead of copying and pasting it from an older app or using the newly created cucumber-rails-training-wheels gem, I decided to accept the challenge and refactor its steps out of the app’s existing features.

After the refactor, the features read much better. They were simpler, less verbose, and felt more maintainable. I also cleaned up my factory_girl usage, which was causing issues similar to web_steps.rb. Here’s a short overview of the main refactorings.

Removing Domain Leakage

The first step in writing a scenario is establishing its context. This usually involves creating some domain objects. For setup, I use factory_girl. factory_girl includes step definitions for calling your app’s custom factories from scenarios.

The following scenario is from a simple CMS. The domain model consists of a single Page class with a page_type attribute. factory_girl factories exist for creating various types of pages e.g., a home page, a category page, a topic page, etc. A hierarchy of pages can be created by associating a page with a parent page. This scenario is for creating a subtopic page.

factory_girl generated the three “And the following <factory-name> exists:” steps from the app’s existing factories. Each of these steps includes a table with the names and values of attributes to be passed to the corresponding factory.

The table in both the category and topic step includes an association. For example, in the topic step factory_girl will set the topic’s parent association to the existing page named “Mind”, or if that page does not exist, to a new page with that name.

There are two problems with this scenario:

1. Dependent on the domain model. This scenario contains the names of classes, their attributes, and even their associations. This is brittle and could break due to domain changes as minor as renaming a database column.
2. Includes too much detail. This scenario is about creating a subtopic, the actual test data should not matter. The fact that the name of the topic is “Stress” is distracting and irrelevant. The home and category pages are also unnecessary; only a topic page should be required to create a subtopic page. Factories should handle any required associations. These nonessential elements are known as incidental details.

Let’s refactor to something simpler.

This refactored version replaces the former setup with a single step, also provided by factory_girl.factory_girl generates a “Given a <factory-name> exists” for each of your factories. This simpler step definition excludes the ascii table filled with implementation details, eliminating distracting test data, and making the scenario more readable overall.

Strive to use factory_girl‘s simpler step definitions to create more maintainable scenarios. Avoid writing scenarios with the more verbose table based steps by eliminating incidental details. Don’t hesitate to create custom steps if factory_girl‘s steps are too low level for a scenario.

Thinking Declaratively

web_steps.rb provides a lot of low level step definitions for performing actions on a web page, e.g., clicking a link, filling in form fields, clicking buttons, etc.

Here’s a scenario from the same simple CMS project using various action steps provided by web_steps.rb.

There are two problems with this scenario:

1. Dependent on the UI. Changes to the UI could result in corresponding changes to this feature. Scenarios written in this step-by-step style are known as imperative scenarios.
2. Contains too many incidental details. A stakeholder doesn’t care about the test data, they just want to verify that you can create a slide.

Let’s refactor and fix these two issues.

A single custom step has eliminated our UI dependency and removed insignificant data. This scenario is much more readable and as a result, more likely to be read.

The important point is to not be lazy and lean on web_steps.rb. Instead, write in a declarative style by creating custom steps that focus on “what” should happen, not “how” it should happen.

Simpler Verification

web_steps.rb also provides several step definitions for verifying page content and form field values.

The omitted verification step of the previous “Create a slide” scenario uses these steps to verify a success message and form field values:

This scenario implies that after creating a slide you’re shown a success message and redirected to the new slide’s edit page. Again, this creates a dependency on the UI and distracts with its “interesting data”.

Let’s refactor by first moving the success message verification into the “And I create a slide” step. Then we can introduce a new higher-level step to summarize the redirection and expected form field values.

Make the Effort

The removal of web_steps.rb was a controversial move but also a good one. Like most developers, I ignored the warnings in web_steps.rb and my scenarios suffered from unexpected failures and UI dependencies. By eliminating web_steps.rb, you’re forced to think declaratively and write your features at a much-higher level. Take the same approach during setup when using factory_girl. I abused factory_girl‘s step definitions and my features soon became lost in ascii tables.

You will have to write more code, but the improved readability and maintenance make it worth the effort.