Cover image from Amazon.com

It's been way too long since I blathered on about style issues. Today I'd like to talk about testing style. This article assumes you are already writing tests and already using something approaching a Test-Driven Development process -- I'm not here to argue about process, at least not today.

Today the topic is the actual construction of individual tests, how to name them, how to group them, where to get data from and the like.

I suspect I'll think of five more things right after I post this, so look for an update sometime in the future. The update will also address all the places where everybody tells me that I'm totally wrong.

Name tests after their expected behavior

The first part of each test is its name. By now, there's no excuse for still using the def test_underscore_instead_of_spaces naming convention. Rails 2.3.x, Shoulda, and RSpec all support a style where the test name can be an actual string with actual readable spaces and everything.

A test should be named after the expected behavior it verifies. Being specific is helpful here -- the name is potentially important documentation.

GOOD: test "should use last_name, first_name as display"

LESS GOOD: test "should correctly display names"

BAD: test "name display"

If you can't think of an easy name to describe the behavior being tested, this is a strong hint that the test is either a) richly deserving of being split into multiple parts or b) unneeded. Most of the time, it's (a).

Use contexts to group related tests

I'm also at the point of feeling like there's no good reason not to use contexts. If you don't want the weight of using Shoulda or RSpec, then just use the Context gem to get simple contexts.

So, what gets grouped in a context?

• A set of tests that all share a common data setup
• A set of tests that exercise a common method, as in controller tests that all work on the same action

Obviously, those two options tend to go together.

The context name should reflect the commonality -- either the name of the method being exercised, or something denoting the common data setup, like "as an administrative user".

Nesting

Contexts can also be nested, allowing for setups to be extended. I don't have very strong ideas on when nesting contexts is advisable, my current guidelines look like this:

• Only nest a context if the inner context uses all of the outer context setup and then adds on (similar to the guideline of only creating an Object subclass if the subclass uses 100% of the parent class data)
• Try to keep the distance between the different setup methods as small as possible -- the problem is that having to trace setup code up multiple pages and across several generations of contexts is a real pain.

Actually, the problem I'd really like a clean solution for is what to do if I want the inner context setup to be run first -- for example, a controller action that I want tested for multiple user types. The controller action is logically in the parent context, but the login as the various user type, logically in the inner context, needs to happen first. Putting a large context for each user type separates the tests for each action, which I'd rather avoid. Anybody smart got this one solved yet?

Setting Up Data

The guideline for creating data for tests is simple: create the minimum amount of unique data that you can while still having a meaningful test. In many cases, a model unit test will only require one object, and in many of those cases only a small number of attributes are actually relevant to the test. (One of the advantages of factory tools is the ability to highlight just those relevant attributes).

Even search and report methods can often be unit-tested with only two models in the database -- one to be found, and one to be ignored. (You'll often need more than one test, but each individual test is small and focused on one unit).

Setup should be as close to the actual test as possible, granted that it often makes sense to group repeated patterns into setup methods.

Single Assertion Style

Shoulda has popularized a testing style where most of the test is in the setup and each individual testing method has a single assertion. I have mixed feelings about this style, though I use it sometimes.

Guidelines:

• If you are going to do single-line tests, definitely use a tool that optimizes single-line tests like Zebra or Testbed.
• I think single-assertion tests work best when setting up relatively simple model tests that don't require a lot of nested contexts.
• Especially in controller tests, single assertion tests can lead to a lot of extra calls to the setup and a slower test suite, so that's something to keep an eye on.

When tests should be DRY and other fascinating questions?

The key thing about tests is that they are also code, so pretty much every style issue that applies to regular code also applies to tests.

That said, tests do have a special place in your application in that they are the part of your code that doesn't actually have tests of their own. So there are some special guidelines for tests.

Don't get cute. There's an old programing truism that if debugging is harder than coding, then by definition any code that is as clever as you can write it is impossible to debug. Similarly, any test written at the edge of your ability is going to be impossible to verify. It's not that metaprogramming and other fancy stuff has no place in testing -- Shoula macros depend on metaprogramming, for example. It's that you probably don't want an individual test to depend on the subtleties of Ruby's object system.

You can repeat yourself a little. I place a higher value in tests on being able to read the whole test in one glance than I do in regular code (I expect regular code to be spread across various methods, I expect a test to be self-contained). As such, I tend to allow somewhat more code duplication in tests than I do in application code, especially in setups. That said, keeping setups short has a value as well, and when the setup is creating enough objects that it's obscuring the point of the test, I'll refactor the setup to a helper method and reuse that. But in application code, I'll generally blast duplication immediately, but in test code, I'll often wait until I have some pain. Is that a good thing? Not sure.

Your turn. Where am I wrong?

The article is written in response to assertions made by one Jakob Nielsson, who, citing numerous eye tracking studies that his team has performed over the years, concludes that any images, or other elements on a web page that are not integral to the site's content or function are routinely ignored, and hence superfluous or even distracting.

But the author says no.  Aesthetic elements on websites, while not recognized as helpful in eye tracking studies, do perform a vital role in website usability.  Mr. Lynch cites the work of early 20th century Gestalt psychologists that have proven that the brain responds to images in milliseconds.  And more recent studies of web sites suggest that users make visual impressions of pages in less than 1/20 of a second--before eye tracking movements begin--and that those impressions more or less stay through the length of the visit.

He goes on from there about why "attractive things work better", describing Don Norman's three levels of human psychological processing (Visceral, Behavioral and Reflective), and why they all work together to create an impression of a product like a website.

Read the full article over here.

Recently I have taken a bit of a detour into the world of telephony, working with Asterisk-Java, which by itself is a very valuable tool, and worth knowing a bit about if you are integrating a system with Asterisk. While it is a Java-based library, I am integrating it into a Grails application.

We have a fairly comprehensive suite of unit tests asserting that desired behaviors are triggered upon certain events initiated through the Event API. This is made even easier, as usual, with Groovy-- specifically on the testing front. Here I show two hypothetical test cases, followed by supporting code that works specifically with the Asterisk-Java classes...

 
import org.gmock.GMockTestCase
import org.asteriskjava.manager.event.JoinEvent
import org.asteriskjava.manager.event.LeaveEvent
 
def queueObject = // .... some object representing an internal queue
 
/*
 * Verifies caller entering a call queue will trigger behavior
 */
void testCallIAddedToQueue() {
  mock(queueObject).add('SIP/123', '3125551234').once()
  dispatchJoinEvent([channel: "SIP/123", callerId: "3125551234"])
}
 
/*
 * Verifies caller leaving call queue will trigger behavior
 */
void testCallRemovedFromQueue() {
    mock(queueObject).remove("SIP/123").once()
    dispatchLeaveEvent([channel: "SIP/123", dateReceived: new Date()])
}
// ...
 

The testcases above are fairly straightforward, hiding much of the details involved when working with Asterisk-Java. The 'queueObject' can be anything, really, as long as it contains behavior which we wired into the event-handling system Asterisk-Java provides. The important part here is how we can easily bind properties to the underlying Event types, and dispatch them so that our behavior is invoked.

 
private def dispatchJoinEvent(properties) {
  dispatchEvent(JoinEvent, properties)
}
 
private def dispatchLeaveEvent(properties) {
  dispatchEvent(LeaveEvent, properties)
}
 
private def dispatchEvent(eventType, eventProperties) {
  def event = eventType.newInstance([:])
  eventProperties.each { name, value -> event."${name}" = value }
  play {
    asteriskService.connection.dispatchEvent(event)
  }
}
 

Here I have a 'service' class defined in Grails which I call 'asteriskService'. It encapsulates access to the Asterisk-Java ManagerConnection instance, which in turn can dispatch specific events.

Of interest to those new with Groovy is the binding of properties within 'dispatchEvent()'. It looks perhaps a bit more complex than one would hope, but unfortunately JoinEvent and LeaveEvent do not have default constructors, requiring the code to 'new' them up with a placeholder argument, and then set any properties on the fly.

Asterisk-Java is worth checking out, but particularly nice is using a bit of Groovy to tie it in nicely. While this can benefit the application, you can see how it helps ease testing-- particularly as you start using more and more of what the library offers.

Not many people talk about good practices to use for comments in code. Many people see them as an extra or freebie, so not a lot of thought gets put into them. The truth is, though, that comments are a great tool for giving insight into the thought process when the code was being written. Unfortunately like any tool, comments can be misused.

Here are three of the most common misuses of comments which I tend to run into.

1. Commenting the Obvious
A.K.A. Superfluous Comments
A good rule of thumb for comments is to not comment on what the code is doing, but why it is doing it. You then try to write the code as self-documenting as possible so that footnotes aren't required to figure out what is going on. Obviously, there are going to be some times when this rule can't be followed because of the complexity of the situation and in those cases comments about what is going on is valuable. However, you will sometimes run into comments for code which is easy to understand

Please take a look at the following real live example from some Flex 3 SDK code which sparked the idea for this post. I would have to assume that anyone familiar with ActionScript would be able to figure it out on their own...
BAD

 
    //--------------------------------------------------------------------------
    //
    //  Constructor
    //
    //--------------------------------------------------------------------------
 
    /**
     *  Constructor.
     */
    public function TextInput()
    {
        super();
 
        // InteractiveObject variables.
        tabChildren = true;
    }
 

When I saw that first giant comment, I thought to myself "hey, this just might be a constructor". When I saw the second comment, I was sold on the idea! Nestle that third comment about InteractiveObject variables into your mind for the next misuse (misleading comments), but try to focus on the first two for this one.

Commenting on very obvious stuff such as "this is a constructor" just creates clutter which reduces the readability of the code. Instead of seeing more code at once, I have to scroll past large chunks of useless information. Whatever "code style" reasons people use as rationalization, these types of comments are unnecessary and don't provide useful additional information or clarity (the whole point of comments). If you feel you need a map to show where things are located, I would suggest refactoring into smaller classes and/or establishing code formatting guidelines (such as, "static variables go at the top above the constructor").

So, knowing this, what should the comments look like?
BETTER

 
    public function TextInput()
    {
        super();
 
        // We want our children to be tab-enabled since our TextField
        // child will be handling a lot of the work, so force this
        // value to true to allow that.
        tabChildren = true;
    }
 

Now, my attention is focused on a useful comment and not parsing through a lot of useless comments.

2. Comment Confusion
A.K.A. Incorrect or Misleading Comments
There are two main causes for this problem. The first cause is if the coder will write a comment that is either incorrect or not very obvious. Sometimes this is because the confusing comment makes sense to the person writing it, and sometimes it is just because the person made a mistake. The second cause is "code/comment drift"; this is when code is updated but the comments are not. Code can change over time, but sometimes the comments that explain what is going on are left behind when the code changes to do something else.

Whatever the cause, incorrect or misleading comments can lead to confusion when the comment contradicts the code in subtle (or not so subtle) ways; you have to dig through source control or old requirements (which are sometimes not updated either) to figure out what the code should be doing. It is an even worse problem if there is no test for the logic in question.

Deleting or updating comments when you change the code seems obvious to most, but I have run into this problem on more than one occasion. The same goes for writing clear comments. I could have used the previous example's comment of "// InteractiveObject variables." to illustrate this point since that is confusing given what the code which follows it actually does , but I'm going to spoil you with an exaggerated fake example.
BAD

 
public int count(List<Something> stuff) {
    // the number of foos we find
    int barTotal = 0;
 
    // count foos
    for (Something it : stuff) {
        if (it.isBar()) {
            barTotal += 1;
        }
    }
 
    // return foo count
    return barTotal;
}
 

Now, judging by the comments, the code has a bug since it should be counting foos and not bars. In a perfect world, the method would be named better to indicate what needs to be counted (self-documenting code) and there would be a unit test which would prove what should be going on. But since we don't have any of that, we are left scratching our heads and spending time looking in source control and old requirements documents to try to figure out what needs to be counted.

What would some better comments look like? (N.B. I won't change any of the code's naming, which is really what needs to be done in this case).
BETTER

 
/**
  * Count the number of bars in the passed list, and return it
  */
public int count(List<Something> stuff) {
    int barTotal = 0;
 
    for (Something it : stuff) {
        if (it.isBar()) {
            barTotal += 1;
        }
    }
 
    return barTotal;
}
 

Notice that I made the comment reflect the code. In the absence of any evidence of what the code should be doing, assume that it is doing the right thing and adjust the comments to reflect that. This piece of code still needs to be investigated to determine if it is a bug or not (no, seriously, just changing comments is sweeping the problem under the rug), but at least the comment confusion has been removed.

3. Not Enough Comments
A.K.A. Failure to Execute
This is probably the most common situation. When writing code, people don't tend to think about maintaining the code or they have difficultly realizing what "unique knowledge" they have about the situation which makes certain things obvious to them but completely confusing to someone else.

Knowing when a comment is needed is an art and it is difficult to give direction. The one piece of advice which I've found useful is to ask yourself the question "if I came back and looked at this code in a year, would I know what is going on?". If not, try to leave comments which would help your future self figure that out.

Take a look at the following:
BAD

 
public void handleError(int errorCode) {
    if (errorCode < 3) {
        errorCode += 1;
    }
 
    notify("received error" + errorCode);
}
 

Now, why exactly do we need to add one if the error code is less than three? What sort of madness is behind this?

Without a comment to tell someone what is going on (or remind yourself), this magic math is a mystery. Do we need to do this? Has the reason for this apparent hack changed since it was coded up? Keep in mind that a unit test wouldn't be much help here unless it had comments or a name which implied why this is being done.

Now, let's take a look at the same code which different comments.
BETTER

 
public void handleError(int errorCode) {
    // to support operations, our error codes need to be translated
    // to their scheme.  the mapping is:
    //     our 3 and up = the same for operations
    //     our 0 = their 1
    //     our 1 = their 2
    //     our 2 = their 3
    if (errorCode < 3) {
        errorCode += 1;
    }
 
    notify("received error" + errorCode);
}
 

With just a simple comment, the reasoning for this math is now known to anyone who looks at the code. A year later, you will be able to look at the code and know why that math is being done.
UPDATE: 3:30PM CT: Again, the correct solution to this problem would be to refactor the code to be self-documenting; however, I wanted to focus mainly on the comment aspect of this instead of improving the code itself. Improving the code would make the comment completely unnecessary, but ignore that for the sake of this example :).

Good coding practices, TDD, and pair programming will play a major role in alleviating comment misuse. However, keeping in mind the rule of commenting the why and not the what will go a long way to improving comment quality.

Fluent NHibernate is an extension of the widely used and very popular NHibernate framework for Microsoft .NET. It is an open source framework that sits on top of the NHibernate layer and utilises all the core NHibernate methods. This framework provides an alternative to the standard XML based mappings (.hbm xml files) of NHibernate. It lets you define the NHibernate mappings in strongly typed and concise C# code.  For those who are new to NHibernate, here is more information.

 Traditional NHibernate XML mapping

 <?xml version="1.0" encoding="utf-8" ?> 
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" 
  namespace="QuickStart" assembly="QuickStart"> 
 
  <class name="Cat" table="Cat"> 
    <id name="Id"> 
      <generator class="identity" /> 
    </id> 
 
    <property name="Name"> 
      <column name="Name" length="16" not-null="true" /> 
    </property> 
    <property name="Sex" /> 
    <many-to-one name="Mate" /> 
    <bag name="Kittens"> 
      <key column="mother_id"/> 
        <one-to-many class="Cat"/> 
      </bag> 
  </class> 
</hibernate-mapping> 

Fluent NHibernate equivalent

public class CatMap : ClassMap<Cat>  
{  
  public CatMap()  
  {  
    Id(x => x.Id);  
    Map(x => x.Name)  
      .WithLengthOf(16)  
      .Not.Nullable();  
    Map(x => x.Sex);  
    References(x => x.Mate);  
    HasMany(x => x.Kittens);  
  }  
}

 Why use Fluent NHibernate? Here are some benefits that it offers:

• It favors convention over configuration and overcomes the repetitiveness that is there with NHibernate. For instance, NHibernate requires string properties to be not null and have a default value. You don't have to handle this if you go fluent.
• By getting rid of XML based mappings, it paves way for easy-to-read code that can be refactored and maintained in a simpler way. The mappings sit along with your code so any refactorings/changes to the code will cause the mappings to be affected as well. This helps catch compile errors/bugs with mappings.
• One other obvious benefit is that the XML verbosity of NHibernate can be avoided.

I think this is a good place to start picking up Fluent. You find a nice little project example that talks about mapping a simple database schema and building an application to read data using the fluent mappings.

photo credit: Marco Arment

Whenever I hear the plan uttered (and in my Wall Street consulting days, I heard this a lot), that we should build an HTML (or Flash) prototype, impress the client and then fill in the back end, an unwanted image comes to mind. We're digging a hole (the missing 80% of the back end) and covering it with leaves (the HTML prototype) in the hopes that the client will fall in (impressing the client).

No, this isn't a rant about HTML, Flash or paper prototypes. Those have their place, to be sure. We use them every day in our own software development practice, but they have a short lifespan -- usually less than an iteration on the way to delivering the actual feature that it is prototyping. But when the prototype takes on a life of it's own and becomes a long-term deliverable, that's when you run into problems. What are these problems? They aren't as numerous as fall leaves, but there are plenty.

The View from the Bottom of the Hole

1. The client thinks you're practically done.

The interface is done, right? So you're practically done, no? Well, no. The sort of unsophisticated client that confuses a slick UI for a working system, is not going to have a lot of patience when you explain that you have to fill in that hole with the actual backend and that will take four times as long as the UI you just sold him. This can lead to...

2. The rotten foundation, or, get it done quick.

photo credit: adamjackson1984

The pressure is on to complete the back end, so you cut corners and slap together the system like the fake town in High Plains Drifter. The resulting software, like all rush jobs, will be hard to maintain and not win you any points with the client.

3. You can't get there from here.

You've developed some really slick interactions in the prototype. Now in building the actual system, you discover that your idea of a transaction doesn't line up with transactions in some third party system you have to integrate with. You either have to change your interface (time for another layer of leaves!) or try to paper over this difference with a likely complex faux transaction layer in your back end. Blech!

4. We propose, but we don't actually do anything.

Regardless of how high fidelity your prototype, it probably didn't actually do anything. Otherwise, you could have actually developed working software in that same time period. If the prototype just looked good but didn't do anything, there was no opportunity to put it in someones hands and see if it did the job. You end up with something that looks good, but likely doesn't fulfill the needs of the prospective users of the system.

The solution to this mess? Don't develop software this way. Deliver working software every week or two and check against real users to make sure it does the job. If you're in a hole, stop digging.

Apple and Google understand in their bones that simplicity and ease of use are essential to broad adoption of products and services. That lesson doesn't come so naturally to Microsoft and IBM.

That's why we integrate user experience design into the agile development process, and that's why we advise our clients to release the simplest software they can early, so they can learn from real user feedback and continue to make improvements based on that learning.

It's like John Gruber writes over at Daring Fireball:

“A complex system that works is invariably found to have evolved from a simple system that worked. The inverse proposition also appears to be true: A complex system designed from scratch never works and cannot be made to work. You have to start over, beginning with a working simple system.”
—John Gall

If there’s a formula to Apple’s success over the past 10 years, that’s it. Start with something simple and build it, grow it, improve it, steadily over time. Evolve it.

Do you understand that in your bones?

I have a native iPhone application in development which requires me to interact with a server that uses a stateful protocol over a persistent connection to transfer messages over the wire. This is definitely not a trivial application to write, even though the UI itself is very simple.

The Problem

Stateful protocols and persistent connections are often interrelated, but not by design. My first problem was to divide the original problem in two: how to manage the persistent connection, and how to handle the underlying protocol so that the stateful aspects did not bubble up throughout the UI.

Persistent connections can be difficult to manage, particularly when the network topology can change so drastically (such as on mobile devices). In this sense, there is nothing new here-- while the framework can notify you of connection events, it is still up to the developer to decide on the appropriate action.

The statefulness of the protocol, however, is trickier to deal with. We must track the state of the connection, and notify the caller of 'certain' errors. I say 'certain' because there is a class of errors that can be dealt with on behalf of the client in a reliable way, affording the rest of the application to treat the protocol as if it were stateless in most cases.

In dealing with the issue of maintaining the persistent connection, I wanted a solution which prevented me from having to manage separate thread(s), run loops, or NSOperationQueue. It is not that these approaches could not work, only that I wanted fewer failure points in the code, and experience has shown that many times there is a better way. Synchronous network calls were obviously not an option (if you didn't get a visceral reaction upon the very idea, just try and go that route-- it is not a happy place to be).

Managing the Persistent Connection

Luckily, AsyncSocket can do much of this for you. It's a great library for this sort of work, and I would recommend it over just using the NS connection classes alone. This library, however, does not do everything for you. You still have to refer to the connection from your code (either through a shared singleton approach, or as an injected dependency).

Managing the Stateful Protocol

I first attempted to create an interface on top of the network protocol, and quickly realized that this path would involve quite a bit of 'target/action' callbacks. So the choice was to either create a delegate protocol around my interface, or else use the NSNotification model to notify interested parties when certain events completed. Again, both of these options are possible, but there was just one problem...

...NSURLConnection and NSURLConnectionDelegate provide a lot of this for you. Knowing this, why wouldn't I want to capitalize on the framework? No synchronous calls, no extra delegate protocols to write. You get certain faculties for free using this route as well-- an established architecture for managing credentials, caching strategies, and in some cases, a way in which you can write and test your application against stateless protocols (say, HTTP) in a controlled, test environment, before actually testing against your custom, stateful protocol (let's presume access to the server is limited).

I was sold.

The Work

At this point, the problem became one of first developing a URL scheme for my needs, and then subclassing NSURLProtocol. My own implementation of NSURLProtocol checks the state of the single, persistent connection on each request, and issues an authentication challenge to the caller if the connection could not be created (this gives the user the ability to intercede, enter a password, or just cancel the connection).

The URL scheme is fairly straightforward, as the 'path' element of NSURL translates directly to commands on the server. Query parameters represent arguments.

The Way Forward

There is still more work to be done, of course, but the architecture is very clear. As mentioned above, I plan to handle changes in the network connection. Without this, a slow cellular connection, say, would still be used even when a faster connection type suddenly became available. Since the handling of the underlying connection is behind the protocol layer, this becomes an easier change to manage than if all parts of the code had to concern themselves with changes in the network connection itself.

My experience so far has taught me a few things about both the URL loading system in Cocoa, and how to deploy these kind of apps in the wild. There are not many examples of NSURLProtocol out there. This is a common complaint, but the points above, along with the existing sample code, should help steer you in the right direction.

I'm unabashedly happy with my phone, because it's strengths and weaknesses mesh pretty well with my actual needs. It's not that great a phone, but I don't use the phone that much. On the other hand, there's never been a better gizmo for whiling away a long train commute.

So, here's some stuff I use:

Instapaper (free light version, $9.99 pro version currently on sale for $4.99)

Instapaper has probably changed my web reading habits more than any other app since I started using RSS readers. It's so simple that its almost hard to believe how useful it is. When I come across an article on the web I want to save for later, I click a bookmarklet. Later, launching Instapaper on the phone, the article shows up, with the images stripped away, and the text presented in a reader friendly format. (Sometimes you can help Instapaper out by invoking it from the printer-friendly version of a page...)

Using Instapaper has become kind of second nature -- I always have a few articles ready to go. The Pro version adds a few nice features, including control of the display font and the ability to scroll the article by tilting the phone. The tilt-scroll sounds like you'll need to be a gymnast or something to read an article, but in practice it's a super-clean interface for reading long articles and letting the text scroll at your reading speed. Great app.

Birdhouse ($3.99)

Very well designed little app for what seems like a dumb use case -- saving drafts of posts intended for Twitter. I mean, how much do you need to polish that tweet about the ham sandwich you had for lunch, amirite?

But, if you are trying to do a tip a day on Twitter (@railsrx), then having a nice place to store up ideas for future tips is great. The app also works as a slightly structured note-taking app, since it can email it's existing draft population back to you.

Stanza / Kindle (Free)

The two leading general-purpose eBook readers, both of them are easy to use, and manage the task of making text readable on an iPhone. It'd be nice if there was some consistency in formats between the two apps, and also if you could buy books directly from the Kindle App (presumably that's coming).

MLB At Bat ($9.99)

Obviously only if you are a baseball fan, but the app gives you access to live box score and play-by-play data, live audio stream of radio broadcast, video highlights, special goodies like condensed game videos a few hours after games and, plus live video streaming on a currently limited basis. That's a lot of stuff. Add in the fact that the app is pretty enough to have won an Apple Design Award, and it's a pretty fabulous package.

Twitteriffic (Free lite, $3.99 no-ads)

There are something like a zillion Twitter clients on the iPhone at last count, and which one to pick is basically idiosyncratic. It's a mark of how fast iPhone development is going that Twitteriffic 1.0 won an Apple Design Award in 2008 and was completely blown away by newer clients six months later before regaining strong status with the 2.0 release. I find this has a nice blend of features and interface. (Tweetie, which is my desktop client, is also very good on the iPhone).

Of course, this all sounds serious -- the big winners on the iPhone have all been games, there are all kinds of inexpensive, addictive little games I play. Here are a few: Defender Chronicles, The Creeps, Drop 7, Flight Control, Frenzic, Galcon, Peggle, Strategery.

photo credit: stuartpilbrow

Your project is going along fine. After the initial bumps, the team has reached max velocity and is running through story points like there’s no tomorrow. The demos are a success, with the client loving how everything is coming together. Communication between the team members and the client is working well, with enough give and take that all sides feel like they have a genuine stake in the project. In fact, the goal posts are in sight and we’re already scheduling a release plan. And then the client asks for one more feature. Not a tweak of something already built, but a new feature that has to seamlessly incorporate into the application and not look like a last minute add-on.

The initial response? The team to comes to a screeching halt and devolves into something resembling the stages of grief.

1. Denial: “But it’s perfect as it is.”
2. Anger: “What!?!?!? We worked so hard to make it work and now they want to junk it up?”
3. Bargaining: “Better to release it as is and then develop new features”
4. Depression: “Stupid project”

Welcome to feature fatigue. Many weeks have gone into creating this software and no one is happy about adding more stuff. I've been through this more than once and it really does seem to be the default reaction. Why? I'm not sure -- too many iterations spent solving problems? Relief that end is in sight only to have it cruelly taken away? Who knows. At some point in your career, you’ll find yourself in this situation and the question is, how to deal with it.

Hopefully, the new request will first have been filtered through the project manager rather than dropped on the team during a demo, as the first path tends to minimize collateral damage. In any event, regardless of how the request is introduced to the team the PM takes on the initial push-back, explains to the client the pros and cons of inserting a new feature at this late date and the effect it’ll have on the release date and/or other areas of the application (not to mention the cost).

It also doesn’t hurt to ask the client for a explanation of their business reason for this latest addition. This isn’t done to make the process difficult (well, not always), but rather to try and figure out if there’s something already built that will meet the business needs. And again, always good to point out the costs of adding in a new feature, especially if existing functionality will meet most or all of the business needs. These discussions will help to determine if this new feature is a “must have” or “nice to have”. It might be that building the new feature is unavoidable, but getting as much background information as possible helps everyone on the team make the best decision.

Once all this information is gathered and presented, the team can then move onto the final stage:

5. Acceptance: “So fine, what’s the new schedule”

followed by, team beers.

The ChicagoRuby users group (not to be confused with chirb.org another great Chicago Ruby user group) held their second meeting at their downtown location.

While the meetings out in Elmhurst are always informative and helpful,  the downtown location may allow for a bigger crowd, and the weekday time might work better for more people. Plus, the Illinois Technology Association - Tech Nexus is right next to Union Station which works great for people that still have to go out to the suburbs.

Noel Rappin's talk covered some of the most common questions he gets through the Pathfinder Development Blog, and his own site RailsPrescriptions site RailsRX.com dedicated exclusivly to testing.

There's too much detail to cover here, but at a high-level, Noel covered:

• The why, how, when, and where questions that make the foundation of a good testing approach
• Testing techniques for legacy projects
• A good review of the different testing frameworks, what their differences are, and some discussion about each (test::unit, shoulda, rspec, cucumber)
• A solid review of different factory tools that go beyond standard fixtures (Factory Girl, Fixture Replacement, Machinist, and Object Daddy)
• Strategies for migrating from Fixtures
• Differences between the mocking frameworks:  Flexmock, mocha, rspec, and RR (double ruby)
• Finding the right balance, and avoiding the pitfalls of 'over mocking'
• Cucumber testing workflow (and where cucumber doesn't work well)

The audience seemed to have a wide range of experience, but all had opinions to share about what they've learned about testing.  After the talk everyone seemed fell into small groups to network and exchange ideas and contact info, and a group gathered around Ray and Noel as they tossed around some ideas on potential future meeting topics "Ruby IDE/Editor review", "Rails Jumpstart", "Coding Dojo".

The organizers took a stab at hosting the meeting virtually over gotomeeting (not sure if it was recorded or not).

Their next meeting is scheduled for July 18th, details can be found in their meetup.com group.

The organizers of the ChicagoRuby.com group are also the organizers of the 2nd annual WindyCityRails Conference right here in Chicago, on Sept, 12th, which Noel will be presenting at.

photo credit: great_sea

A few weeks ago Alice Toth and I had a conversation about how we can better serve our clients, and while we normally delve into project efficiencies like communication, developer training, and good QA practices, this time we both concluded that we need to do a better job of helping our clients reach their goals in the most efficient way possible, and sometimes that means talking them 'down' from the specific implementation idea they have, and finding a faster way to get there.

I said that one of our challenges is that sometimes our clients feel they've hired us to just  'Mow the Grass', not discuss the landscape architecture, so we're not always in a place to be heard when it comes to discussing the fundamentals of a project.  Alice wrote a nice post about what 'Just Mow the Grass' meant to her, and the strategy she's devised to find a nice middle ground.

Here's how I see it

I was thinking about the times when we encounter projects that are looking for what I call 'commodity software development' which is to say they feel they already have all the requirements, and everything is all figured out, and they just need a fixed-bid project to have it built. The reality though is that most of the time the idea is not fully fleshed out, and needs a good deal of work. While there might be some giant spreadsheet of features, usually the core business goals aren't clear, and many fundamental issues have not been covered.

If the customer thinks they have hired us to just 'mow the grass', they aren't in a place to hear any ideas about the big picture, they simply want us to 'build it', and as a consulting company we do need projects, and we want to have happy customers, so it seems we can either just build exactly what they asked for, and hope it turns out for the best, or we can help them confirm the business fundamentals a bit, and verify that the plan will work.

"I didn't hire you to question me"

Its not easy to get into the fundamentals with our customers, but the overall success of our work is dependent on knowing the fundamental assumptions that led to its creation, and in my mind that means we need to explore those ideas and test them out.

The other comparison/metaphor I had been kicking around in my head goes like this:

Imagine you are a building contractor. You build buildings to meet the needs of your clients, while adhering to the 'best practices' of your industry. If a client comes to you and wants you to build a new 'asian-fusion' restaurant in an area that you are pretty sure its not going to take off, you could suggest that another location might work better, but in reality, the customer probably isn't interested in what a contractor has to say about the viability of a concept restaurant. If the concept doesn't take off, the contractor still got paid, the builing is still standing and can be used for other purposes, and an outsider would not conclude that the restaurant failed because of anything related to the structure of the building itself. And while it might seem that the contractor doesn't care if the concept restaurant succeeds or not, let's suppose that if it had been successful it would lead to a long and successful relationship where the contractor and the business owner continue to work together on new buildings and projects.

So in this example, the 'building' project has specific and measurable requirements that are independent of the big picture success of the restaurant.

Now comparing that to a software development project that is core to the business. The software product that is created is inextricably linked to the success of big picture, and the software is unlikely to stand on its own and be usable for some other business. In fact if the big picture is not successful often times the software product itself is blamed.

Some of the fundamentals of a project

1. Is this a problem that users care about?
2. Is this the best way to solve that problem?
3. Is the business value greater than the cost to build it? (if not, how could we either lower the cost, or increase the value?)

I've noticed this fundamental failure to align the proposed features of a product to their expected return more on iPhone projects, and other smaller budget projects. That's not to say that its not present on larger projects, just that its more noticeable on smaller projects.

Ok, so now what?

Where as I was suggesting that we need to just dive into the fundamentals of the project and balance out the features relative to their expected value, and that its our job to 'Fight' to make sure we're building the right solution to the right problem, Alice's suggestion was that we need to consistently deliver high-quality results on the tasks we've been charged to do, even if it is just 'Mowing the grass', in order to establish trust and credibility, and earn our place at the 'big table' of advice giving.

What I don't like about Alice's idea is that its simple, elegant, logical, and its not mine!  (There's nothing worse than someone taking something you said and interpreting it to be more positive and cohesive than you realized)

You may have won this round Alice, but what will you do with customers like these?

When you improve a little each day, eventually big things occur. -- John Wooden

photo credit: mister b 1138

A few weeks ago I had a discussion with some colleagues on the adoption of Agile within large corporations. The consensus was that Agile was almost always adapted rather than adopted -- that is, companies exclude those practices that conflict with corporate culture, modify those that seem too impractical or wasteful, and sometimes substitute those internal practices that seem a decent and familiar substitute.

Various schools of Agile thought have different reactions to this adaptation, all negative. The XP folks particularly don't like it.

These [thirteen] practices support one another...and thus care should be taken when modifying any of them, or deciding not to include one or more of these practices in a project.

I agree that it definitely helps to follow a particular Agile approach closely in the beginning. Once you have the basics down, you can start to improvise. But it helps knowing the fundamental principle which, in my opinion, underlies all of the agile practices, no matter what the flavor. So, the first three commandments of Agile software development are:

1. Feedback loop
2. Feedback loop
3. Feedback loop

Pair programming is about the feedback between two developers that improves code and design quality. Test driven development is about designing testable software that then provides you with feedback when you change the system. Iterative development is about getting feedback from incremental releases of your software. Iteration retrospectives are quite obviously about garnering feedback about how the team and process worked or didn't work.

Whenever something isn't working in your project, try to identify the source of the problem and design a feedback loop to monitor and adjust that source. But be careful. Not all of the feedback is about the same thing. Iterations and releasing software early and often is feedback intended to improve the software product, while iteration retrospectives are intended to improve the development process. They both are about continuous, gradual improvement however. These aren't bandaids or crutches, they are not about fixing something temporarily, but about making it better for the long haul.

Sometimes, the problem isn't the absence of a feedback loop but the fact that it is too long or too arduous. When something doesn't work, you want to know about it now, not in a week. You want it to fail fast. That's why we have short meetings, or scrums at the beginning of every day and why we try to release software every 1 or 2 weeks. Also, the feedback has to be dead simple to get, which is why we automate as much of it as possible. Continuous integration is a good example of this.

Armed with this understanding of the feedback loop, you can now safely adjust an agile process to fit your corporate culture. Feedback has to be quick and automated if it is to be successful. So, if your primary product user travels internationally much of the time, you need to shorten that feedback loop, perhaps by recruiting a proxy user that our international traveler trusts. On the other hand, substituting your company standard practice weekly status meetings for a daily scrum is an example of substituting longer and more arduous feedback. Nobody wants to sit through a 2 hour status meeting once a week, so the practice degrades over time. Five to ten minute daily scrums, on the other hand, are as easy as they are useful.

It sometimes takes a little experience and noodling to figure out what exactly you are trying to improve. You're seeing a high bug rate and lots of build breakages. What is the cause? Perhaps a pair of developers is checking in code every week instead of several times throughout the day. It is breaking the changes of some other developers. The solution might be to put in an automated system in your continuous integration server that warns the team if a particular developer hasn't checked anything in in a while or if they have checked in a huge number of files.

Getting the entire team to be agile feedback detectives is really the way to go. Pride of ownership and self interest -- a good process means no software death marches -- will go a long way toward engaging everyone in process improvement.

I'd love to hear from you about whether you agree that the feedback loop is the core principle of agile, and also any stories -- funny, uplifting or sad -- about adapting agile in a corporate environment.

via Daring Fireball.

AGILE AND ME a story with just enough documentation.

A typical waterfall project produces pages and page of end-to-end requirements for the entire project as it is envisioned (but not necessarily as it will be built). The people compiling these requirements are, of course, part of an assembly with only the most cursory involvement with others outside their department. After all 9,238 lbs. of paper are heaved over the wall with a hearty “good luck!” and a cheery wave, the silos are once again in place and silence is golden.

While agile was taking hold of development, design was still stuck in the waterfall method. So why not blend the two and run the entire project in an agile fashion, starting with requirements? Here's how we do it at Pathfinder:

Like what you see? Check out more of Pathfinder's presentations, whitepapers and articles here.

Windy City Rails is September 12, 2009

Here are a couple of upcoming Ruby and Rails-based appearances by Pathfinder personnel:

On Tuesday, June 23, Noel Rappin (referring to himself in the third person) will be the guest speaker at the Chicago Ruby.org monthly meeting. The meeting starts at 6:00 at Chicago Ruby's downtown loop meeting location, see the link for details. The working title of my talk is "I'd Like To Start Testing. Now What?" and it'll be an informal discussion of testing tools and good practice.

The schedule for WindyCityRails was announced this week. The conference is September 12, 2009 at the Westin Chicago River North. John McCaffrey from Pathfinder will be presenting "Super-easy PDF Generation with Prawn and Prawnto", and I'll be up there with "How To Test Absolutely Anything".

Other speakers include Ryan Singer from 37signals, Ben Scofield from Viget Labs, and Yehuda Katz from Engine Yard.

Registration through August 1st is $99, there are a couple of tutorial sessions also available for purchase.

This was a very well-run regional conference last year, and I'm excited for this year's edition. Hope to see you there.

"I have tried Campfire, and I'm still not quite sure why people pay for it. I think you can take simplicity too far personally. It could be replicated on a weekend (As was done at google with huddlechat) so I don't see the value proposition there." Source

With apologies to Mike Godwin, I like to think of the following as Nolker's Law: As any technical discussion of a web 2.0 product grows longer, the probability of a claim that it can be built in a weekend approaches 1.

Inevitably, it's part of a larger claim: X is trivial to implement, therefore X is not valuable. You see variations on this argument everywhere: Netbooks are made of cheap components and yesterday's technology, therefore they're a fad. My 6 year old could paint that Rothko.

For the last time:

Cost: How expensive it is to build.
Value: How much your customers will pay for it.

They're not even close to the same thing.

Start with Basics: Books, Tutorials etc.

Yes, getting hands dirty is the first thing. If you are "programmers don't read manuals" type and/or you know enough about the new language, just download and give it a ride. Or you can pick a book or two, read getting started tutorials and then give it a try. The gist is start relating what we learn to what we already know and ask questions. How can I upload file in the new framework, how do I do testing, how can I write library/reusable-code etc.

All major language framework now-a-days have atleast 2 types of mailing lists: user and developer. It's a good idea to subscribe to user mailing list and start reading it from a few weeks or months ago depending on how fast the language is changing and how relevent the posts are to current version.

All this may get you coding and get by for the day but you haven't really understood the framework. Fear not, here are a couple of things you can do.

Download and Peruse Example Apps

Most frameworks come with an example application where it is being used to exhibit its strengths. If not, it shouldn't be difficult a reputed open-source project even if the framework itself is proprietary. This is a good place to learn best practicies and design patterns as it applies to that framework.

Subscribe to Bug Tracker

Bugs and new feature requests are a great way to learn about the the "other" side of a cool framework, the deficiencies that is. No quick tutorials focus on the internal nitty-gritty that we run into as soon as you start on a non-trivial project. The discussions that happen on whether something is a bug or a design choice becomes clear from this place. Again, not a bad idea to go a little back in timeline to read fixed bugs, and finished features.

Subscribe to Core mailing-list

Peek into the future that is. Here is where the core maintainers discuss what is the next high priority items are and how to implement them. While it may be too early to contribute here, it is a place to learn some advanced stuff.

Download and Peruse Source Code & Tests

This takes time but it has tremendous advantages. The code is the full truth. Besides good coding practices, it also helps us understand the undocumented features of a framework. And, if code is the full truch, tests are the key to that truth. Tests help us understand what was being achieved in a piece of code.

Pair and Ask Questions

Pair with somebody who has had a head start with the new language. This can quickly give us the soft side tools: the efficiencies your pair spent time building and websites, blogs they use.

blogs/wiki/screencasts

Tutorials, API documentations, technical articles has always been there and are important. Blogs and Screencasts are even better since they are the most current and most applicable to current state of affairs with the language or framework.

Blog your experience

Yes, blogging about your experience will help you learn a new framework. Others who read your blog will point out what you have missed and point you in the right direction. It is also a place where you have documented your journey to refer back to.

Work for Consulting Company

No, this is not entirely madeup Keeping up with latest technologies is a survival trait for any consulting company and its employees. This is where we can meet other motivated folks with different interests and keep up with what is new out there. With plethora of new languages and frameworks coming and going each day, you have to be able to pick winners to add to your tool box. Blogs, RSS feeds help but a lunch time remarks from experienced gurus can go a lot further.

Photo Credit: Daniel Voyager

1. Tether **
2. Run more than one app at a time (background processing)
3. Support multiple browsers (IE, Opera, skyfire, Iris)
4. Multimedia messaging **
5. Use a storage card for music, pics, etc

** While there are plans for the iPhone to support tethering and multimedia messaging, AT&T has not yet announced when it will be available.  (whereas I am writing this on the train right now, tethered to my phone, with just a basic data plan).  So I understand that it will be coming soon to the iPhone, but is not available yet.

To be honest I feel strongly that the first 2 are solid points, whereas the rest kind of quickly decrease in value, but I tried my best to come up with 5 things that mater, and I previously had 'Record Video' at #3, but now the iPhone will support that, so I had to take it out.

Tethering

While I saw good reviews of the Samsung BlackJack when I was in the market for a new phone, tethering was the #1 reason I bought the phone instead of an iPhone. Being able to get on the internet with my laptop from anywhere, at anytime is a very big deal for me. I take the train to work, and often have to rush out the door at night in order to make the schedule, but its easy for me to keep working from the train, and finish up my emails, check-in/deploy code, connect to vpn, etc. and that flexibility is huge.

As a consultant it means I can provide assistance to my customers in a more flexible manner. I recently had a customer contact me with an emergency deployment issue while I was on the road, about 20mins into a 4hour drive. While still on the phone with the customer I was able to plug my usb cable in, fire up my laptop, securely connect to their network, view the logs, debug the issue, change the code/configuration, check in to github, deploy and close out the tickets over the course of 2hours, all without losing connectivity (and picking up Wendy's on the way!).

At one point I had tried to find telnet/ssh tools for my phone that would allow me to do some work from the phone directly, but I find its just easier to tether and use all the tools of my laptop.

Running Multiple applications

Being able to run multiple apps at once is more important than I originally realized, as it helps me to be much more productive and connected.

Some recent use cases of mine are:

1. Using Fring to IM a colleague about an important work email, while walking to the subway, drafting a reply to that email, opening a new tab in my browser to check the bus schedule (if its on time I'll take that instead of the train)
2. Pulling up google Maps while on the road (while someone else is driving of course) to see the route to a friend's house, using Fring to IM that friend that we'll be there soon, and looking up events going on that weekend in the area.
3. Talking on the speakerphone to a customer while looking for some info in email and google docs

Mulitple Browsers (or browser engines)

This might not be a very strong point as the browsing experience on the iPhone is pretty damn good, but I am happy to have:

1. Multiple browsers for different uses (IE for simple mobile browsing, Iris/skyfire for a more powerful experience)
2. Flash video support in the browser (YouTube, Hulu), with Skyfire

* I realize there are different browser options for the iPhone, but my understanding is that they all share the same platform (ie. none of them support flash in the browser)

Conclusion

For me the real lesson here is that I am motivated by 'tool envy', (insert joke _here_). This is just like what I have experienced when pairing with someone using intelliJ when I was on eclipse, or they're on a mac when I'm working on windows and its something that can drive you to look at your environment and ask "how can I make this better?" For windows mobile users I think it takes a bit of effort to find the things that make the phone better, and its a shame that Microsoft hasn't made this process eaiser. Once the iPhone has tethering, and with lower prices coming, its much harder to justify buying anything other than an iPhone.
(oh, and let me know if there is anything else I missed)

You can find more information at the google code project and check out a demo here.