StevenHarman.net

Reading Code is Key to Writing Good Code

Steven Harman — Wed, 18 Nov 2009 22:32:57 GMT

As humans we seem to have an innate desire for structure in our lives. Structure permeates through our societies; it’s found within our families, education systems, governments, etc. I suppose it’s no surprise then that we also seek to force structure upon the work that we, as software developers, do.

The problem is the work we do isn’t structured. It is not deterministic. There is no grand blue print, process, nor methodology that we can follow to pay dirt.

We live in a chaotic and complex world that is itself continuously changing and adapting.

Software product development is a creative activity taking place in the midst of that complex and adaptive world. So doesn’t it make sense that we, as software developers, might benefit from admitting that we are indeed doing creative, unstructured, adaptive work? I sure think so!

Looking outward for inspiration

I’ve recently been looking outward to other creative professions and trades for inspiration and insights into how they work. One thing I’ve realized is that those folks spend an immense amount of time studying and seeking inspiration from the work of others both within and outside their own field.

For example, a musician doesn’t just sit in his garage all day, banging out albums. He listens to and is influenced by the music of many other musicians. An author doesn’t simply site down and write manuscript after manuscript. She spends countless hours reading the classics, studying the words, flow, and style of other authors. The same thing goes for painters, actors, architects, etc. And all of these people are constantly immersing them selves in works outside their area; musicians reading Hemingway, singer/song writers studying Salvador Dali, painters listening to Mozart, cats and dogs living together…

How arrogant of we programmers then to think that we won’t, or don’t, benefit from reading code written by – gasp – someone else!

Read, learn, and be inspired

In my experience we spend a great deal more time reading code than actually writing it. Whether it be the code you wrote just a few minutes ago or something you’ve inherited and are now maintaining, you’re reading it. Of course, that’s only considering the motive of reading code because you’re currently working with.

The greatest motivator for reading code is the opportunity it provides for learning and serving as a source of inspiration. Reading code exposes you to techniques, view points, styles, idioms, and algorithms that you may not have otherwise come across.

In my own career it was by reading code written in Ruby that I first started to develop an appreciation for beauty and aesthetics in code. It also opened me to new ways of thinking about problems and exposed many pains and frictions with the techniques I had been using to that point.

Where to start?

I realize it’s probably obvious, but I’m going to say it anyhow – a great way to start reading other’s code is to pull down an Open Source project and dive in. Of course, that’s not to say that all Open Source code bases are necessarily examples of great code… so you might also want to leverage your network to find examples. Or, use your Google-fu to see what others are reading. Or maybe check out:

Katacasts by Corey Haines and Chris Parsons
The Weekly Source Code series by Scott Hanselman
other suggestions… leave a comment and I’ll update this list!

Technorati Tags: programming,improvement,open source,code

Signing 3rd Party Assemblies without Recompiling

Steven Harman — Thu, 01 Oct 2009 17:54:15 GMT

We recently ran into an issue where upon pulling some new 3rd party dependencies into our product our CI pipeline broke! I when I say broke, I mean it came to a screeching halt!

We were totally unable to compile in Release mode due to the new dependencies not being strongly named and signed. The error message in the build log was

CSC : error CS1577: Assembly generation failed -- Referenced assembly 'MvcContrib.FluentHtml' does not have a strong name

Sign it yourself!

Eric Hexter, of the MvcContrib team, pointed me to a thread explaining how to strongly-name and sign the assembly without having to recompile it. After a few failed attempts, I ended up using the IL Disassembler and Assembler to get the job done. The template for a single DLL follows.

   1:  > ildasm {path\to\assembly}.dll /out:{path\to\assembly}.il

   2:  > move {path\to\assembly}.dll {path\to\assembly}.dll.orig

   3:  > ilasm {path\to\assembly}.il /dll /key={path\to\SigningKey}.snk

The second line could really just be a delete, but whatever. The point is, the third line is going to output a new DLL of the same name as the original, so get rid of the original first.

After that, I committed the new assembly into our source tree, the CI build pipeline kicked off, and we were back to green!

Technorati Tags: .net,trick,security

Prefer Dependency Injection to Service Location

Steven Harman — Fri, 25 Sep 2009 22:30:25 GMT

There is currently a thread running over in the StructureMap Users mailing list asking if we really need constructor injection when using an Inversion of Control container. Before any one rips off on a rant let me say that I worked with Jon in my former life and I’m fairly certain he’s merely conducting a thought experiment, trying to sure up his own beliefs. A worthwhile exercise, if you ask me.

At any rate, I have a few points I wanted to throw out there; most of them basic and mere reiterations of the words of others… but I’m gong to do it anyhow!

The question at hand

I would encourage you to go read the full thread (it’s a quick read… 4 minutes, tops!), but knowing many of you are lazy like me, I’ll reprint Jon’s original question here.

Again, please go read the full thread so you have the full context.

Whenever I tell people about StructureMap (or using DI in general), I
mention that two of the benefits are that (a) StructureMap will create
objects and all their dependencies for you and (b) it enables you to
fake out the dependencies in a test.

Why do we need constructor injection to do this? I can call
ObjectFactory.GetInstance() anytime I want and it will work. And I
could leave SM configured for my tests and call ObjectFactory.Inject()
to stub things out.

So theoretically, I wouldn't even need constructor injection, right?

Let’s get the jargon down

To be clear, Jon proposing using Service Location rather than Dependency Injection.

While Service location is better than poor-man's DI, using it as suggested above is still introducing a high degree of coupling as all of these classes now have an opaque and highly concrete dependency on the container. This is effectively creating a new form of Global. Eww!

The key to using Service Location within new code is to keep it tucked away in the deepest, darkest corners of your infrastructure. For example, if you’re building something on the asp.net mvc stack, you might use Service Location within a custom IControllerFactory to create each of your controllers.

If you’re dealing with legacy code, full of concrete dependencies, you might use Service Location as technique for teasing things apart with a goal of decreased hard coupling. In the end this may result in wholesale replacement of some modules.

When it comes to Dependency Injection and dependencies in general, I agree with Scott Bellware's point of view; make your dependencies explicit & transparent by requiring them in the constructor. My gut reaction is also to avoid translucent (setter-injected) dependencies as they make it harder to tell what dependencies an object will need to do its job – the shape of the object isn’t as clear as with explicit constructor dependencies.

Feeling the friction

I tend to be lazy and prefer to feel friction of poor design early so I can change direction quickly. For example, when a constructor gets too large it's a signal to stop and consider Single Responsibility Principle, Separation of Concerns, etc. In a similar vein, I don’t usually advocate use of an auto-mocking container. Or at least not for folks who’ve not yet acquired a strong nose for design and simplicity; the friction helps keep you on the rails.

Later in the tread Jon mentions some friction he’s been feeling when setting up the context of his tests (or specs). Namely he’s having to set up and inject a lot of concrete objects for interaction within his unit tests. To me this is an indication that those tests may actually be integration tests. After all, they are flexing the integration of a several modules in concert, right?

I say, call them what they are, fire up the fully configured container, and move on.

I prefer to make the implicit explicit, to be able easily see the shape of an object, and in getting forced feedback when my design starts to slip off the rails.

Technorati Tags: Dependency Injection,BDD,TDD,design

Creating a Fluid jQuery jqGrid

Steven Harman — Fri, 21 Aug 2009 16:24:10 GMT

I’m just going to come right out and say it, I have a huge nerd-crush on jQuery. I have for several years. Actually, it may be more of a love affair.

Recently I’ve been spending extra time with the jqGrid plugin, a fantastic mechanism for displaying tabular data in hip & trendy webby-2.0 sites. One limitation I quickly ran into was the grids insistence on a statically defined layout. More precisely, the grid only works for a fixed width, meaning no fluid layouts.

Let’s fix that!

I spent a few minutes spelunking the jqGrid documentations and found that you could set the grid’s width dynamically, via some jQuery-fu. Thirty minutes later I had a grid that could grow or shrink to its parent container, automatically.

On the urging of a co-worker, Andy Edmonds, I invested a little time and extracted the code into a stand-alone module.

I wanted to create a plugin that would monkey-patch the jqGrid, adding the functionality directly to it. But for now it’s a simple jQuery plugin that acts on an instance of a jqGrid.

Check out the demo if you want to see it in action.

UPDATE: I’ve fixed bug in finding a parent element when none is provided. I also changed the option ‘base’ to ‘example’ to avoid a naming collision with some other jQuery stuff.

How to use it.

   1:  $(document).ready(function(){

2:

   3:    // wire up your grid

4:

   5:    $("#theGrid").fluidGrid({ example:"#grid_wrapper", offset:-10 });

   6:  });

There are only a couple of options available right now for configuring the fluid grid.

example : a jQuery selector for the DOM element the grid will use to get a new base size. If none is provided, default to the grid’s parent element.
offset : number of pixels added to the example element’s size, giving the grid its new size. This can be positive or negative. If none is provided, default to zero (0).

The above sample will resize the grid when the page loads, but that’s it. If you want true fluidity, you’ll also need to wire up a handler for the window.resize event to resize the grid. I did just that in the demo listed above, which is really just the sample included in the source code.

The source?

Oh yeah, that stuff. You can grab the source, which comes with a sample implementation, over at CodeIncubator. Please feel free to send me feedback, patches, etc…

Enjoy!

Technorati Tags: jquery,jqgrid,javascript,open source,VersionOne

Being Lazy with Rake

Steven Harman — Fri, 29 May 2009 21:08:37 GMT

I’ve noticed Rake has been gaining some traction within the .net community as of late, or at least within a certain segment of that community.

We’re currently using Rake to automate the great bulk of an entire deployment pipeline here at VersionOne, and I know of a few teams at Quick Solutions that are doing similar things.

I believe Rake is a great tool for automating intensive processes and/or tasks and also find it to be great for handling some of the more mundane tasks we do on a daily basis. I spend a fair amount of each working day in a terminal window – running various SCM commands, compiling code, running specs, etc.

More of those trivial tasks are being replaced by simple Rake tasks. For example, I’ve started adding a Rake task something like the following to nearly every code base I work on

   1:  desc "Launch the solution in Visual Studio"

   2:  task :sln do

   3:    Thread.new do

   4:      system 'devenv #{@props[:solution_path]}'

   5:    end

   6:  end

This is a pretty simple task:

spins up a new thread within a block
then opens a new subshell via the system command
launches Visual Studio (via devenv) passing the path to the solution file.

As long as I have Ruby and the Rake gem installed I can execute the task from anywhere within my project structure and have Visual Studio open the solution.

It may seem incredibly lazy, but it comes in very hand if you like to keep your fingers on the home row. Not to mention the time saver it is on No Mouse Thursdays!

Full Disclosure: I didn’t come up with this little time saver on my own. I was inspired & then stole it from Aaron Jensen, though I’m sure he was motivated by a similar level of laziness. :)

Technorati Tags: ruby,rake,productivity

Toward a Better Use of Context/Specification

Steven Harman — Wed, 27 May 2009 17:19:53 GMT

If you’ve hand-rolled your own Context/Specification apparatus to support your ~~test~~ spec-first lifestyle, you’ve likely got a base class that looks something like the following:

   1:  public abstract class concerns

   2:  {

   3:    [SetUp]

   4:    public virtual void setup_context()

   5:    {

   6:      context();

   7:    }

8:

   9:    protected virtual void context() {}

10:

  11:    protected virtual void decontext() {}

12:

  13:    [TearDown]

  14:    public virtual void cleanup_context()

  15:    {

  16:      decontext();

  17:    }

  18:  }

The above is basically co-opting an existing unit testing tool into something more language-oriented and behavior focused. In this case we’ve built upon MbUnit, adding a couple of hook methods that are responsible for

setting up the context before an individual specification - context
optionally doing any necessary teardown after each specification – decontext

An example

Using this base class, we’ll end up with specs that might looks something like

   1:  using Skynet.Core

2:

   3:  public class when_initializing_core_module : concerns

   4:  {

   5:    SkynetCoreModule _core;

6:

   7:    public void context()

   8:    {

   9:      //we'll stub it...you know...just in case

  10:      var skynetController = stub<ISkynetMasterController>();

  11:      _core = new SkynetCoreModule(skynetController);

  12:      _core.Initialize();

  13:    }

14:

  15:    [Specification]

  16:    public void it_should_not_become_self_aware()

  17:    {

  18:      _core.should_not_have_received_the_call(x => x.InitializeAutonomousExecutionMode());

  19:    }

20:

  21:    [Specification]

  22:    public void it_should_default_to_human_friendly_mode()

  23:    {

  24:      _core.AssessHumans().should_equal(RelationshipTypes.Friendly);

  25:    }

26:

  27:    // more specifications under this same context

  28:    // ...

  29:  }

Here we’ve set up a common context that holds true for each of specifications that follow it. This is also a common pattern used in classic unit testing and in fixture-per-class style Test-Driven Development. In fact, the only real between the above and what I’d have done in fixture-per-class style TDD is the_use_of_underscores, intention revealing names, and the context hook method.

Is that really any different?

These modest cosmetics are not what differentiate Context/Specification from other styles of test-first development. For me, the core differentiator is the realization that there are often many contexts under which a particular behavior my be exercised, each producing an observable and possibly different set of results.

More directly, with Context/Specification we’ll often have many fixtures per class/feature/functional area of the code base. Doing this allows us to keep the context as simple as possible and focused on the behavior being specified. I’ve found that I tend toward having a single file-per-class/functional area, with any number of contexts (fixtures) in each file.

Another big change is that specifications should be side effect free. To be more exact, the specification is actually an observation about the interactions that occurred while or the state of the system after some behavior has been exercised.

Make it explicit!

We want small, focused contexts, yes? And we want side effect free specifications too, yeah? So why not leverage our tools to help guide us in that direction? YES!

Consider the following tweak to the concerns base class

   1:  public abstract class concerns

   2:  {

   3:    [FixtureSetUp]

   4:    public virtual void setup_context()

   5:    {

   6:      context();

   7:    }

8:

   9:    protected virtual void context() {}

10:

  11:    protected virtual void decontext() {}

12:

  13:    [FixtureTearDown]

  14:    public virtual void cleanup_context()

  15:    {

  16:      decontext();

  17:    }

  18:  }

Such a base class will only set up each context once, no matter how many specifications are made against the context. This does a couple of things for us

requires side effect free specifications
guides us toward smaller, more focused contexts
might actually make our specs run faster!

As for the running faster bit, that is not guaranteed as it really depends on how you were writing your specs before making this change.

Some things to watch for

If, however, you were following more of a fixture-per-class style, you might find a drastic reduction in how long it takes your spec suite to run. The corollary is, of course, that you likely don’t have small contexts. That is trouble and is often an indicator that the one, large context is itching to be split out into two or more discrete contexts.

Upon switching your base class over to this more rigid Context/Specification pattern, you might also find that you have some – or many – broken specs. This is an indicator that those broken specs were not side effect free. Well, actually its suggesting that some of the sibling specs weren’t side effect free and they are now causing other specs to break.

Notes:

The portions of this article relating to changing from a standard context set up to a once-per-fixture style apply to most of the hand-rolled Context/Specification base classes I’ve seen in the wild.

If, however, you are using a tool like MSpec, then you’re in good shape as Aaron applied this same philosophy out of the gate. And if you’re not using MSpec, I’d encourage you to take a look at it for inspiration, if nothing else.

Technorati Tags: contextspecification,bdd,tdd,mspec

So Long Columbus, and Thanks for All the Fish!

Steven Harman — Fri, 06 Feb 2009 05:22:42 GMT

Yes, that’s right Columbus… after nearly a decade here, it’s time for me to move on. But don’t worry Columbus, you’ll always be a special place in my heart – and likely irreversible damage to both my psyche and liver for me to remember you by.

Leaving Columbus is a bittersweet thing for me. I’ve got a great group of friends, a metric crap-load memories, experiences I’ll never forget, and a network of some of the greatest colleagues and co-workers in the biz.

Speaking of the biz, the decision to leave Quick Solutions was not an easy one. QSI is chock full of some of the smartest, most passionate, and dedicated folks I’ve ever had the pleasure of working with. I’m really going to miss the team I worked with every day, and I’m especially sad I won’t be around to see the team continue to push the boundaries and reap the rewards of some of the seeds of change we’ve planted together.

So what’s next for me?

I’m headed to The ATL

That’s right, on February 14th I’ll be packing up my car and heading down to Atlanta. I’ll be spending Valentine’s day cruising down I-75, followed by an evening tearing up Atlanta with some crazy cats I know down there.

And then on the 16th, I’ll be starting my new gig as member of the rockin’ VersionOne development team. I spent a full, as in 13-hour-long, day visiting/interviewing with the VersionOne crew a short while back and I’m really excited about being part of what has the potential to be a truly legendary team.

I’m really looking forward to getting back into the product business and focusing on a domain that I’m passionate about – helping drive continuous improvement in an Agile team, building products for Agile teams. Sweet, right!

I’m pumped to see just how far this team can Agile and Lean, and I’m really looking forward to sharing those experiences with you, as we go.

So long, and thanks for all the fish!

Technorati Tags: career, life, Quick Solutions, VersionOne, Columbus, Atlanta

A Little More Sugar for Testing Routes in asp.net MVC

Steven Harman — Fri, 06 Feb 2009 04:44:11 GMT

The other day I was spec’ing out some new routes for my application and I wanted to make sure certain routes were ignored. Not happy with the disgustingly-verbose way of testing routes OOTB with asp.net MVC, I decided to lean on the great work Ben Schierman did in his fluent route testing extensions.

I whipped together a quick extension method that allows me to do the following:

   1:  public class when_requesting_a_gif_file : with_routes_configured

   2:  {

   3:      [Test]

   4:      public void should_ignore_the_route()

   5:      {

   6:          "~/my_file.gif".ShouldBeIgnored();

   7:      }

   8:  }

Building the extension was a snap – I leveraged the work already in place for the other fluent route testing extensions, and just made sure the RouteHandler responsible for the given route pattern was a StopRoutingHandler. It looks something like this:

   1:  public static class RouteTestingExtensions

   2:  {

   3:      public static RouteData ShouldBeIgnored(this string relativeUrl)

   4:      {

   5:          RouteData routeData = relativeUrl.Route();

   6:          routeData.RouteHandler.ShouldBeOfType<StopRoutingHandler>();

7:

   8:          return routeData;

   9:      }

  10:  }

And that's all there is to it!

~~I’ll be submitting~~ I have submitted this as a patch to MVC Contrib project within the next few minutes. Hopefully I can coax one of the committers into applying it. But until then, just steal my code and roll it into your code base!

Technorati Tags: aspnetmvc, fluent, bdd, asp.net

A Sketch of our Ideation Pipeline

Steven Harman — Tue, 20 Jan 2009 20:49:34 GMT

This is an initial sketch of an Ideation Pipeline my team will be using to help drive the direction of a product we’re working on. The sketch is based on a discussion we had about how we currently get from an idea to delivering on that idea, and how we’d like to do that going forward.

While we probably should have done a full on Value Stream Map, we didn’t. And the only excuse I have is that we’re kicking this product off so there isn’t really a set way we do things… not yet anyhow.

At any rate, later today I’ll be turning this loose sketch into a physical Kanban board that we’ll used to track and pull ideas through our ideation process, and feed the resulting features into our development process.

But first, I want to explain how the whole thing will work, or at least how we’re going to start – I’m sure we’ll tweak and straight-up change out whole parts of this process as we go along. Let’s get started!

Starting with an Idea

Our process starts with an idea. An idea can be nearly anything that someone thinks will add value to the system. An idea might be laser-focused, or it might be a bit more nebulous. At this stage we don’t really care, its only important that we realize we have a potential value-adding idea and that we act upon it.

The Standardized Work (designated by the blue text in the lower box of each stage) in this stage is pretty basic, though not necessarily easy. In essence, an idea needs to be evaluated to determine it will deliver value.

And what does deliver value mean?

Value is…

Seen though the eyes of those who pay for, use, and derive value from the systems we create.

There are many factors that go into determining if something is or is not valuable. In our case it’s things like market demand, product vision and roadmap, feature parity with competitors, availability of resources, effort, etc… Also, value is a temporal thing. So while an idea might not hold much promise for delivering value now, that doesn’t mean that it won’t at some point in the future.

If it’s determined that an idea will deliver value now, the idea card is moved into the Ready for Decomposition state. However, if the idea won’t deliver value now (or at least within the very short, foreseeable future), it’s moved to a Never state. In the physical world that means the Idea Kanban is taken off the board.

But wait… if the idea has potential to provide value in the future, and you’ve moved it to Never, won’t we lose track of it?

YES, exactly! And you know what? We don’t care! If the idea truly has potential for some future value, it will come back into our pipeline on its own. Why waste time, effort, and money keeping track of a huge backlog of stuff that might not ever happen? DMZ that stuff!

Ready for Decomposition

Right now we have no queue limits on our Ready for Decomposition queue because we’re

thinking our throughput will be high enough to keep the queue short anyhow
going to help our customers be honest with themselves and diligent in determining which ideas really will provide value

However, if we find this queue to be a bottleneck, or a source of thrashing, we’ll likely put a limit on it.

The first thing that needs to happen when any idea enters the Ready for Decomposition state is to re-prioritize the queue. This needs to happen so the team knows which ideas are most important and should be decomposed first.

Decomposing an idea means doing necessary analysis activities to understand and flesh-out the idea, break the idea down into one or more Minimum Marketable Feature (MMF), and defining acceptance criteria (in a loose Context/Specification style) for each feature. During the decomposition the MMFs are transitioned to physical Kanbans that will feed into and flow through our development pipeline. These are also known as Feature Cards within our organization.

When to decompose?

Idea decomposition is not a regularly scheduled activity, but is triggered by a downstream need for Feature Cards. That is, ideas are pulled through the Ideation Pipeline by some downstream activity that will move the idea closer to providing value. We’re pulling from Concept to Cash!

It should also be noted that we only decompose as many ideas as are needed to satisfy the source of the pull. In this case, that would be our development pipeline’s backlog queue. If the backlog has two spots open, and we decompose an idea into two MMFs, then we’re done decomposing for now. If we only decompose it into one MMF, then we’ll need to decompose another idea.

And what if that second idea decomposes into two or more MMFs? Now we’ve got more MMFs than we can fit in our backlog… oh no!

Actually, that’s just fine! Our development backlog is itself a prioritized queue. So we just need to prioritize all of the MMFs, fill the backlog with the most important ones, and let the rest sit in the Decomposed state until the backlog pulls another one in!

On to the development pipeline!

Well… that’s what those MMF Kanbans would do anyhow! But you, dear reader, will have to wait until later – like until I write a post that covers our development pipeline!

Other Resources

If you’re looking for more information on some of the terms or concepts I’ve mentioned here, be sure to check out Karl Scotland’s excellent round-up of links/references to materials on Kanban Software Development.

Technorati Tags: lean,kanban,software,process

Saving the World via… TDD?

Steven Harman — Wed, 14 Jan 2009 05:55:56 GMT

Hot on the heels of my wildly (in)famous “When Should I Write Tests?” post, I have another fun tidbit about testing to share with you. Though, to be honest, I found this gem via my buddy Scott C Reynolds, so I can’t take all – actually, I can’t take any – of the credit.

Anyhow, Scott posted a great little snippet of code that does a couple of things:

Shows the gist of Context/Specification style specs in use.
Ensures we won’t need John Connor’s help after all.

using Skynet.Core

public class when_initializing_core_module
{
    ISkynetMasterController _skynet;

    public void establish_context()
    {
        //we'll stub it...you know...just in case
        _skynet = new MockRepository.GenerateStub<ISkynetMasterController>();
        _skynet.Initialize();
    }

    public void it_should_not_become_self_aware()
    {
        _skynet.AssertWasNotCalled(x => x.InitializeAutonomousExecutionMode());
    }

    public void it_should_default_to_human_friendly_mode()
    {
        _skynet.AssessHumans().ShouldEqual(RelationshipTypes.Friendly);
    }
}

public class when_attempting_to_wage_war_on_humans
{
    ISkynetMasterController _skynet;
    public void establish_context()
    {
        _skynet = new MockRepository.GenerateStub<ISkynetMasterController>();
        _skynet.Stub(x => 
            x.DeployRobotArmy(TargetTypes.Humans)).Throws<OperationInvalidException>();
    }

    public void because()
    {
        _skynet.DeployRobotArmy(TargetTypes.Humans);
    }

    public void it_should_not_allow_the_operation_to_succeed()
    {
        _skynet.AssertWasThrown<OperationInvalidException>();
    }
}

Originally I wasn’t going to repost the code here because I didn’t want to take credit for it. But after a quick chat with Scott I decided maybe I should, just in case Pastie decides to take a dump! Plus, this is like a little time capsule of our current thoughts on Context/Specification, pop culture, and the ceremony of many of the languages we currently use.

But as a matter of full disclosure, here is a link to the original code on pastie.org.

Technorati Tags: tdd,bdd,contextspecification,terminator