Girl Writes Code

The Future of Blogging*

2012-05-15T23:34:00.000-05:00

Here's how this is going to work. I have technical blogs on Los Techies and Headspring, but this here blog is the one with the cute domain name. Wondering what to do with Girl Writes Code, I remind myself that I enjoy writing about cooking and climbing and travel as much as I enjoy writing about code.

So I will continue to post technical content to those blogs, and this one will feature posts about the rest of my life, with pointers to the tech posts on the others. You can subscribe to either of those blogs, or to this one for the union of all three.

* on this blog

Running JavaScript... With Sneakers!

2011-11-16T20:31:00.001-06:00

Code-review time. I haven't written significant JavaScript in forevs, but I hit upon a use case well suited to it, had a blast coding it up, and am confident that I'll be completely mystified by it three months from now. That is, unless we refactor it for maintainability (this is where you come in).

I'll explain the use case. The Couch-to-5K running plan is an excellent exercise regimen for learning to run. I followed it to successfully transform myself from sedentary software developer to 5K finisher. The runners among you know that five kilometers is a beginner-level distance; the sedentary software developers may find it as daunting as I once did. You train in intervals, alternating walking and running, gradually shifting the ratios to more running in successive workouts. If you can walk a moderate distance, following the program is totally doable (or modify it for easy walking/fast walking, if you're not up for jogging). Definitely check it out.

The thing is, timing the intervals—especially at the beginning, where you're alternating a minute of running with 90 seconds of walking—needs a complex timing device (a fancy runners watch), and if you're using a treadmill, it is really annoying to your fellow gym users, as your watch is beeping every minute or two. Or, well, maybe gym people don't care, but it's really annoying to me, since the dang thing is on my own wrist. For running indoors, I want a C25K timer that is tactile or visual. I've been thinking about an Arduino-powered timer that reads from a dip switch to determine which workout you're running and signals the changes with a vibration motor (like in a cell phone). Thinking, and not so much doing. Finally one Sunday I forced myself to focus on the problem: what do you have, with a visual display, that is really small and runs code?

My Nokia N810 internet tablet has a web browser that runs JavaScript, can open html files stored locally, and can do this while also playing a podcast. Win!

Here's what you can't do with JavaScript, though: Thread.Sleep(walkInterval). Instead, you use setTimeout() to say "execute this function after this interval," asynchronously. That's the part that currently works but I daren't touch it. In other words, that's the part that needs your code review advice. Remember that the intended scenario is to rest the tablet on the treadmill's magazine lip, so the app flashes the background of the page to catch my eye when I'm not looking directly at it. It's high-contrast because it isn't meant to be watched, just kept at hand, in my periphery.

If you choose to use the app (in addition to reviewing it), please only use it on a treadmill. Stay safe; don't try to wrangle something you need to look at while you're on the trail.

The Running Timer code is on github. A representative sample is below. How would you make it better?

var exercise = function(setup) {
 var workout = getWorkout(setup.week, setup.day);
 doExercise(workout, 0);
}

var cooldown = function() {
 walk('Cool Down');
 window.setTimeout(function() { transition(function() { walk('Done!'); })}, 
  minToMilli(RT.cooldownDuration));
}

var doExercise = function(workout, i) {
 workout[i].mode();
 if (i === workout.length - 1) {
  window.setTimeout(function() { transition(cooldown) }, 
   minToMilli(workout[i].minutes));
 } else {
  window.setTimeout(function() { transition(function() { doExercise(workout, i + 1); })}, 
   minToMilli(workout[i].minutes));
 }
}

var getWorkout = function(week, day) {
 return eval('C25K.W' + week + 'D' + day);
}

var transition = function(callback) {
 var indicatorDiv = $('.runCountdown');
 var body = $(document.body);
 transitionBlink(6, indicatorDiv, body, callback);
}

An Object Lesson in Binary Compatibility

2011-08-22T09:34:00.010-05:00

A riddle for you, friends: When is changing a method from return void to return Something a breaking change?

If you already know the answer, then why hadn't you told me? Could've saved me a fair bit of embarrassment. Ah well, maybe I missed your call.

First, a story

I had the opportunity to contribute to the HtmlTags open-source project1. They needed some unit test coverage, and I <3 unit testing and wanted to try my hand at contributing to open-source software. As I got my bearings, I got more confident and started to reach beyond the unit test project into refactoring the application code.

That's when I found the AddStyle and AddJavaScript methods. Their friends returned an HtmlTag, but they returned void. They would be easier to test if they returned an HtmlTag, but that's not a good justification for changing a method. But they would be more consistent if they behaved like their neighbors, and that is a sufficient justification to consider it.

HtmlTags is a library meant to be consumed by other applications. It was already in use in the wild. Therefore, it was important not to change its API. It had to work like it always had, else we'd cause considerable grief to the developers using our code. I've been the consumer of a service that made breaking changes to its API, and I have choice things to say about the team that saddled me with that noise.

I thought really carefully. I was contemplating changing the return type of a public method in an in-use API. But all those uses would be calling it as if it returned nothing, and you can invoke a method without using its return value. This would be just like that. I asked a coder-buddy for advice. We convinced each other: What harm could it do?

What about the riddle?

Here we come to the answer to the riddle. If you're changing a library that will be called by other applications, then there are many seemingly harmless changes that are actually breaking changes, including changing a method's return type. When the consuming assembly is compiled, it is built with instructions to find a method named Whatever that returns void, but the changed assembly's manifest contains only a method named Whatever that returns string. No match.

Computers. They're so literal.

To fix it, you merely need to recompile the consuming application, but you don't discover the problem until assemblies are loaded at run-time, an annoying time to discover exceptions. I coded up a simple example that illustrates the problem. Feel free to follow along at home.

See the problem in action

Make two separate solutions, a class library called MessageOutputter and a console application called ConsoleMessager that references MessageOutputter. First, build MessageOutputter with a return void method.

namespace MessageOutputter
{
  public class Outputter
  {
    private string _message = "This is the outputter, version 1.";

    public string Emit()
    {
      return _message;
    }

    public void UpdateVersion(string versionNumber)
    {
      _message = string.Format("I've been altered by the UpdateVersion method. I am version {0}.", versionNumber);
    }
  }
}

UpdateVersion modifies a private field but does not return a value. Compile that solution and put its dll into a lib folder from which you will reference it in ConsoleMessager. Open the ConsoleMessager solution and add a reference to the MessageOutputter.dll. Write a method that uses the MessageOutputter.

namespace ConsoleMessager
{
  class Program
  {
    static void Main(string[] args)
    {
      var outputter = new MessageOutputter.Outputter();
      Console.WriteLine("Calling the outputter:");
      Console.WriteLine(outputter.Emit());
      Console.WriteLine("Asking the outputter to update, then calling it again.");
      outputter.UpdateVersion("Updated 1");
      Console.WriteLine(outputter.Emit());
      Console.Read();
    }
  }
}

The UpdateVersion method is called, not expecting a return value. Build and run the ConsoleMessager.

Return to the MessageOutputter solution and modify the UpdateVersion method to return the message after it modifies it.

namespace MessageOutputter
{
  public class Outputter
  {
    private string _message = "This is the outputter, version 2.";

    public string Emit()
    {
      return _message;
    }

    public string UpdateVersion(string versionNumber)
    {
      _message = string.Format("I've been altered by the UpdateVersion method. I am version {0}.", versionNumber);
      return _message;
    }
  }
}

Now UpdateVersion returns a string. Build the solution and copy its new dll back into the lib folder, and into the Debug or Release folder under ConsoleMessager/bin, so that the ConsoleMessager will run with your new version of the dll. Run ConsoleMessager and you will encounter the error:

Unhandled Exception: System.MissingMethodException: Method not found: 'Void MessageOutputter.Outputter.UpdateVersion(System.String)' at ConsoleMessager.Program.Main(String[] args)

The MissingMethodException indicates that ConsoleMessager, when looking within the MessageOutputter library, could not find an UpdateVersion method that returns void. Reopen the ConsoleMessager solution. Before you even build, IntelliSense will tell you that UpdateVersion returns a string now. Build ConsoleMessager and run it again, to see that it works successfully.

Wiser now

No one raked me over the coals—in fact, my intro-to-OSS experience was thoroughly positive, and I can't wait to do more—but I know I caused some time-consuming inconvenience to my fellow devs. I have now learned that Binary Compatibility is not the same as Source Compatibility. Conflating the two is like saying, "Works on my machine." I hope this write-up can help you avoid a similar goof.

1 The nice thing about open-source projects is that everyone has the opportunity to contribute. But I had the especially good fortune to have willing help from Josh Flanagan in finding my way through my first OSS pull request.

Using Syntax to Model the Domain

2011-06-20T18:25:00.010-05:00

I'm fascinated by the small syntactic decisions that bring code closer to representing the business domain. Never mind the class inheritance examples from text books ("Dog IS-A Pet," which has nearly never been relevant), I mean using properties, methods, and constructors to let the compiler ensure your objects stay in a valid state. Linguistically, I think this is neat.

Not everything deserves a setter

Consider my Bacon class with an IsCooked property:

public class Bacon
{
  public bool IsCooked { get; set; }
}

To cook some bacon, I set IsCooked to true. Sure. But what if I set it to false? I just defied physics and the space-time continuum. Shucks.

IsCooked should be read-only, and I need a different way to change it in a one-way transition: I need a method. Bacon comes into my domain uncooked, so I'll set that property in its constructor.

public class Bacon
{
  public bool IsCooked { get; private set; }

  public Bacon()
  {
    IsCooked = false;
  }

  public void Cook()
  {
    IsCooked = true;
  }
}

The sanctity of thermodynamics is preserved. When the transitions get more interesting than a simple Boolean, you're looking at a state machine.

Polywhatism?

I encountered this example in the wild, but I've changed the domain to protect the innocent.

We're exploring a dungeon, and in our inventory we have items that affect our health:

amulets add a small amount to our health each day;
granola bars give us a lump-sum boost to our health the moment we eat them; and
cursed rings sap away our health each day until the curse runs out. (Why keep a cursed ring? How else would you command your army of winged monkeys?)

Here's a display of our inventory:

Item	Daily Boost	Total Remaining
Obsidian amulet	150
Luck ring	(25)	375
Jasper amulet	253
Granola of righteousness		400

This was implemented as a collection of IHealthItem objects. Here's what I found:

public class Amulet : IHealthItem
{
  public int? DailyBoost { get; set; }

  public int? Total
  {
    get
    {
      return null;
    }
    set
    {
      throw new NotSupportedException(
           "Amulets do not have a total");
    }
  }
}

As if the cursed rings weren't bad enough, now there are properties we're not allowed to call, lurking, waiting to pounce on us with a run-time exception. The calling code, when working with an IHealthItem instance, is forced to make an "Is" check to determine the type, in order to know which properties are safe to use. Half the properties aren't relevant half the time. The DailyBoost property on CursedRing has an additional problem: Should you set it to a negative number, or assume it should be stored as an absolute value and multiplied by -1 when being used and displayed? The IHealthItem interface does not provide any abstraction.

In fact, these are not three variations of the same thing. The only quality they have in common is the user's desire to see them displayed in a table. (Further proof that they weren't related, in the real application, that table was labeled "Amulets/Granola Bars/Cursed Rings.") These concepts should have been modeled as three independent entities, keeping it unambiguous in the business layer how to use them to increment and decrement the adventurer's health. Only at the presentation (UI) layer, they could be projected into a display-only DTO (Data Transfer Object) or view model, using strings for all three properties.

Don't let me be uninitialized

If a property must be set for an object to be in a valid state, the class's constructor should require that value as an argument instead. That way, it's impossible to construct the object without also putting it into a valid state.

If a method, MethodB(), uses a private field and relies on another method, MethodA(), to be called first to set it, MethodB should take that value as a parameter instead. That way, MethodB can be called only after the result of MethodA has been determined; the correct order in which to call them is unambiguous.

These types of temporal coupling are illustrated nicely with examples and remedies on Mark Seemann's blog in "Design Smell: Temporal Coupling." (He has a whole series on encapsulation.)

Too, meaning drives syntax

When I find myself compelled to explain in comments, to write instructions ("make sure you set this before you call that") in the xml summary, to incorporate usage notes into method names, I pounce on that as a candidate for refactoring. Finicky methods and classes that require secret knowledge to use correctly are invitations for bugs. It's like when I'm editing the rules for one of Jon's games: every instance of the word "except" must justify its existence. Every special-case exception immediately draws my attention as a spot where the rules could be improved and streamlined. Similarly, when coding, certain behaviors draw my attention as opportunities for improvement. Hyper-explainy documentation is a big one.

Semantics is the study of meaning, and syntax is the study of structure. That distinction makes them sound like separate domains, but the two interpretations of "foreign car mechanic" stem from syntactic ambiguity. Each word still carries the same meaning, but in one case "foreign" modifies "car," and in the other, "foreign" modifies "mechanic." Syntax in natural languages certainly influences meaning, so why not in code, as well?

Diffing Files to Avoid Easy Goofs

2011-05-17T17:51:00.000-05:00

A good habit learned at my last job has saved me a lot of embarrassment and bugs (same thing): Before committing a set of changes to source control, I look at the diff of each file. Look at the changes, read 'em over, look for misspellings and placeholder notes-to-self and files I hadn't intended to change; then make fixes and revert as needed. It's like proofreading. Polishing the fingerprints off a product before sending it into the world. Checking your knot.

Shortcuts for diffing files:

In TFS, Shift–double-click a file name in the Pending Changes window. (You can configure TFS's diff tool.)
In TortoiseSvn, double-click a file name in the "Changes made" panel of the Commit window.
In git and Hg... help me out here. I'm too used to a visual side-by-side. Recommend a nice explanation of getting the most from those in-line diff reports?

If that seems daunting because there are so many files to review, check in more often. I appreciate the mentors who have drilled into me: small, focused, atomic changes. It keeps me focused on what I'm doing. Make this one change, and every other stray thought that leaps to mind ("Ooh, I need to do this, too!") gets tossed in a running text file, to be addressed later. How small is small enough? When it no longer feels onerous to diff all your files before checking in. ;-) In addition to keeping my thought process on-track, this habit makes it easy to review, fix, unwind, and selectively pick certain changes when I need to.

Small check-ins are like the extract-method refactoring. In code, when you have a collection of statements that do something, you'd extract them into a method so that you can name the something. Similarly, a focused check-in can have a descriptive and useful check-in comment.

The three habits fit together: small check-ins targeting a focused goal, with a useful commit message, reviewing the changes before checking them in. Reduces the number of times I have to think "Who the heck did—?! Oh, me. Heh."

Microcontroller Projects and Source Code

2011-03-09T21:10:00.000-06:00

Welcome, Ignite/Dorkbot Science Fair Party Goers. Here are details on the two projects I had with me at the Science Fair.

I used the open-source Arduino microcontroller. Arduino programs are called "sketches." I keep my Arduino sketches on the collaborative source-code repository GitHub, in my Arduino-Sketches repository. You can browse the code in a web browser without installing Git, so go check it out. And then learn Git and post your own sketches.

The Ambient Clock is an information radiator for the passage of time. It was written up on the Makezine blog. (pictures | program)

The Blinky Eyeball Halloween Nightmare is, um, pretty self-describing. (write-up | pictures | program)

Hello World in C, Dev Setup

2010-12-29T15:24:00.001-06:00

As mentioned, I'm learning C, and I've achieved hello-world, plus recursive calculations of factorials and some data structures. Whee. :) For those playing along at home, I'll describe my dev setup.

But first, an unexpected discovery: Counter to my intuition, there's a beneficial synergy between learning a new editor and learning a new language at the same time. I had thought it would be too many new things to take on at once. I've wanted to learn Vim for its beautiful efficiency, but its formidable learning curve repels all comers. I couldn't gain traction. When writing in a language with which I am comfortable (C#, English), my thoughts would run too fast, too far ahead of my rudimentary editor skills, ideas slipping out of my grasp as I stumbled around the text with j, k, h, and l (and never the one I meant). But in C, where I am carefully picking my way over unfamiliar terrain, my lines of code have slowed down to match my fingers. Because I am trying to hang onto only one edit at a time, I can spare a second to check that A will switch me to insert mode at the end of the current line. I recommend it: learning a new language is a good time to learn a new text editor.

Sandbox

I use VirtualBox to run virtual machines. VMs are excellent for experiment-based learning; think of it: a nice clean server that you can start up, poke and abuse, throw away and start again. If you start with the right VM image—for example, one configured for Ruby on Rails—you can jump right into the experimentation without all the installation hoop-jumping.

For this endeavor I chose TurnKey Linux's Core appliance because it's just Linux and not much else, following their instructions for installing a TurnKey appliance.

To install a compiler (later), I needed my VM to connect to the internet. In VirtualBox Settings > Network, I set "Attached to" to "Bridged Adapter," meaning the VM could use my laptop's connection, and the adapter's "Name" to my wireless card. (The other choice in the dropdown list is a PCI-E Fast Ethernet Controller, and that... didn't work.) With that set, I powered up the VM, which starts the webmin console. I let it automatically configure DHCP, and I was internet-ready.

Editor

Vim is already installed on the Core VM image, so I just needed to type "vim helloworld.c" to start stumbling around my new code file. I'm relying on the TuXfiles Vim cheat sheet.

Compiler

I chose GCC, the GNU Compiler Collection for my C compiler, and I needed to download and install it. Following TurnKey's apt-get instructions:

apt-get update (to update apt's list of modules)
apt-cache search gcc (to find modules for the gcc compiler - gcc-4.1 looked right.)
apt-cache show gcc-4.1 (to get info about it)
apt-get install gcc-4.1 (to install it)
gcc-4.1 myfile.c -o myexename (to compile and generate myexename executable)
./myexename (to run my program)

Hello World

I followed a video that creates and compiles a C program using the GCC compiler. "Hello, World!" A simple phrase, profoundly satisfying.

Dipping into C

2010-12-03T08:11:00.001-06:00

I decided on Monday that I should learn C. Cultivate a nodding acquaintance, at any rate. Louis is always prodding me to become a better craftsman, to become more proficient with my tools. So I figured I should understand my roots.

I picked up O'Reilly's Mastering Algorithms with C at the library, and I'm already having fun. It will get into recursion, Big O notation, linked lists, quicksorts, encryption, and all that jazz, but right off the bat, it starts with pointers.

Immediately some aspects of C# become more clear, by understanding their precursors from C: the ideas behind reference types and passing parameters by reference, and the joys of automatic garbage collection and abstracted memory allocation.

The syntax of pointers in C involves a lot of punctuation—a subtle and nuanced application of asterisks and ampersands—which the book assumes I would already know. My favorite search engine (code-named Sweetie, as in, "Hey, Sweetie, can you find...") turned up an online edition of The C Book, containing this excellent explanation of pointers.

Here's my understanding so far. Please suggest corrections if I've gotten it sideways.

int *mypointer;	mypointer's type is "pointer that can point to an integer"
mypointer = &myint;	mypointer is pointing to the location where myint is stored
*mypointer = 7;	the place where mypointer is pointing now contains a 7, so myint now equals 7
myotherint = myint;	myotherint also equals 7 (but just a copy of 7, so changes to myint won't affect myotherint)

So what? So now I'm clearer about reference types in C#. In C, I can pass a pointer as a parameter to a function, instead of passing a value. That means I'm passing the function a reference to a location in memory. If the function uses the pointer to change the stuff in that location, when someone else accesses that location, they will receive the changed stuff. Contrast this with passing a value, such as an integer, to a function, which actually passes a copy of the value. Any changes to the value are scoped within the function and are not detectable from outside. It's something I've known for a while, but now I know why.

If you no longer need the piece of memory that a pointer points to but you fail to de-allocate that memory, it will stay held in reserve forever—voilà, a memory leak. Different data types take up different amounts of memory, so writing a data type into a pointer of a differently sized data type will overwrite other pieces of memory in unpredictable ways. I feel like I've been making peanut-butter sandwiches with a butter knife and just noticed that other people are wielding samurai swords: looks really powerful and flexible, but I'm scared I'd cut off a finger. Now I get what the big deal is about the CLR's garbage collector (and how in some contexts it would be too restrictive).

I'm having fun getting "closer to the metal" and realizing the reasons behind some things I've taken for granted. I can't wait to get into the chapters on algorithms.

Three Simple Steps to Improve Your Writing

2010-08-30T12:16:00.001-05:00

Technical books are longer than they ought to be. Most software books could be improved by shedding a tenth of their heft. It's a product of market pressures, of course: Tech books need to get to market fast, which does not allow for the time-consuming labor of honing and refining a text until it is lean and tight. I have a few simple strategies, though—simple tips that provide a disproportionately beneficial return on a trivial time investment. You can use the following tips to improve your blog posts, books, and presentations.

Replace "basically" with nothing.

This word never adds value. It is usually a manifestation of the author's or speaker's unconscious concern that what he is explaining is too complex. If time allows, revise the material until your readers don't need extra convincing that it is basic. At least get rid of the useless word.

You could have some fun writing a regular expression to correct all instances with a global search-and-replace. If you're amused by the challenge, please feel free to post your regex in the comments. You'd be helping all of us.

Here are the replacements your regex would need to catch:

Find	Result
Basically, it can start a sentence.	It can start a sentence.
Basically people leave off the comma, too.	People leave off the comma, too.
It can basically appear in the middle.	It can appear in the middle.
It can, basically, be set off with commas.	It can be set off with commas.
It can end a sentence, basically.	It can end a sentence.
It might end without a comma basically.	It might end without a comma.

Replace "essentially" with nothing.

As above.

Replace "is nothing more than" with "is."

The "is nothing more than" construction falls in the category of noisy hedge words. It's a large category. Folks add words to forestall arguments. Even though it sounds romantically brash—X is nothing but Y, #wristforehead—it actually weakens the association between the subject and its predicate nominative. Be clear; be bold. If you're trying to define X by saying that it is Y, say that X is Y.

I wish the industry allowed more time for editing. I wish I were able to help more people express their ideas. Good editing is liberating, plucking the brambles and cruft off a passage until its central theme floats to the fore—getting the text out of the way of the writing.

I hope you find these tips helpful and easy to implement. Ruthlessly delete useless clutter like "basically," "essentially," and "nothing more than." Let your ideas stand tall.

ReSharper Shortcut for Context-Sensitive Unit-Test Running

2010-06-19T20:40:00.007-05:00

For a keyboard shortcut to the context-sensitive ReSharper unit test runner (otherwise available via right-click > Run Unit Tests), map:

ReSharper.ReSharper_UnitTest_ContextRun

(Thanks to Clinton for mentioning it.)

What This Solves

The slowest way to select and run unit tests is to click the green-yellow bubbles in the left margin and pick "Run" (or "Append to Session" to collect a bunch of them to run).

From the right-click menu, the "Run Unit Tests" option will run a test if your cursor is in a test, all tests in a fixture if your cursor is outside a test but within the fixture, or all tests in a file if you're outside any fixtures.

Mapping the ReSharper.ReSharper_UnitTest_ContextRun to a keyboard shortcut achieves the context-sensitive behavior, mouse free. I chose Alt-T for mine, since that wasn't in use for anything else. (Have a nice strategy for picking unique keyboard shortcuts and remembering them? Please share in the comments.)

To Map the Shortcut

Tools > Options > Environment > Keyboard. In the "Show commands containing" textbox, enter some or all of the command, and select the command.

Set your focus to the "Press shortcut keys" textbox and type your shortcut just as if you were invoking it. If a command shows up in the "Shortcut currently used by" list, life will be simpler if you pick a different shortcut. When you have one you like, click "Assign" and "OK." Good to go!

Rhino Mocks Examples, with a fix

2010-03-18T22:17:00.002-05:00

Jon Kruger created an excellent explanation of Rhino Mocks, using unit tests to demonstrate and illuminate the syntax and capabilities. (Found via @gar3t.) It needs one small correction, which I'd like to write about here so that I can link to and support Jon's work, and because it gives the opportunity to clarify a subtle distinction between mocks and stubs and verified expectations.

First, go check out Jon's code, then come back here.

The problem lies in the following test. I can comment out the part that looks like it is satisfying the assertions, yet the test still passes—a false positive.

[Test]

public void Another_way_to_verify_expectations_instead_of_AssertWasCalled()

  var stub = MockRepository.GenerateStub<ISampleClass>();

  // Here I'm setting up an expectation that a method will be called

  stub.Expect(s => s.MethodThatReturnsInteger("foo")).Return(5);

  //Sneaky Sharon comments out the "Act" part of the test:

  //var output = stub.MethodThatReturnsInteger("foo");

  //Assert.AreEqual(5, output);

  // ... and now I'm verifying that the method was called

  stub.VerifyAllExpectations();

In translation, that test says: Create a fake ISampleClass; set up an expectation that a method will be called; ~~call that method~~ do nothing; verify that your expectations were met (and flag the test as a failure if they weren't). Shoot. Worse than not having my expectations met is not realizing they're not being met. Reminds me of my college boyfriend.

There are two things to fix here. The first is that this test is a little solipsistic. If you create a mock, tell the mock to act, and verify things about the mock... all you're testing are mocks. Instead, you want your tests to exercise real code. The "system under test," i.e., the class being tested, should be part of your production code. Its dependencies are what get mocked, so that you can verify proper interactions with those dependencies. Let's fix the solipsism before going on to the second issue.

As originally written, the expectation would be satisfied by the "Act" (as in Arrange-Act-Assert) part of the test. It says, "Call this method. Did I just call this method? Oh, good." Instead, you want to ensure the system under test correctly interacts with its friends, using Rhino Mocks' AssertWasCalled and Expect methods. We need a real class that takes the stubbed class and calls a method on the stubbed class, and we'll write unit tests around the real class.

public class MyRealClass

  public void ActOnTheSampleClass(ISampleClass sampleClass)

Here's the re-written test, verifying how my real class interacts with the ISampleClass interface.

[Test]

public void Another_way_to_verify_expectations_instead_of_AssertWasCalled()

  var stub = MockRepository.GenerateStub<ISampleClass>();

  var systemUnderTest = new MyRealClass();

  // Here I'm setting up an expectation that a method will be called

  stub.Expect(s => s.MethodThatReturnsInteger("foo")).Return(5);

  // Tell the system to act (which, if it is working correctly,

  // will call a method on the ISampleClass.

  systemUnderTest.ActOnTheSampleClass(stub);

  // ... and now I'm verifying that the method was called

  stub.VerifyAllExpectations();

This test will still pass, despite the fact that my real class does not currently call any methods on the ISampleClass interface. This points to the second issue to fix. In Rhino Mocks, expectations on stubs are not verified; only mocks are verified. If an object is created with GenerateStub instead of GenerateMock, then its VerifyAllExpectations method doesn't do anything. This is non-obvious because the AssertWasCalled and AssertWasNotCalled methods on a stub will behave the way you want them to.

In Rhino Mocks, a stub can keep track of its interactions and assert that they happened, but it cannot record expectations and verify they were met. A mock can do both these things.

That is how they are implemented in Rhino Mocks. If you were holding firm to the ideas in Fowler's Mocks Aren't Stubs article, I think stubs would implement neither VerifyAll nor AssertWasCalled. Semantically, verifying expectations and asserting interactions are synonymous, if you ask me; therefore, stubs shouldn't do either one.

Back to Jon Kruger's tests. If we call GenerateMock instead of GenerateStub, the test will fail properly with an ExpectationViolationException.

[Test]

public void Another_way_to_verify_expectations_instead_of_AssertWasCalled()

  var stub = MockRepository.GenerateMock<ISampleClass>();

  var systemUnderTest = new MyRealClass();

  // Here I'm setting up an expectation that a method will be called

  stub.Expect(s => s.MethodThatReturnsInteger("foo")).Return(5);

  // Tell the system to act (which, if it is working correctly,

  // will call a method on the ISampleClass.

  systemUnderTest.ActOnTheSampleClass(stub);

  // ... and now I'm verifying that the method was called

  stub.VerifyAllExpectations();

Now that we're red, let's get to green. Change the system under test so that it does its job as expected.

public class MyRealClass

  public void ActOnTheSampleClass(ISampleClass sampleClass)

    sampleClass.MethodThatReturnsInteger("foo");

Wahoo, a passing test that we can rely on.

The two key points from this exercise are:

Describing Rhino Mocks with unit tests is a cool way to explain a topic. Let's have more executable documentation, eh?
Expectations on stubs aren't verified, so beware of falsely passing tests.

New home for RSS feed

2010-03-18T22:10:00.001-05:00

A friend recommended FeedBurner, so the RSS feed for Girl Writes Code will be served from http://feeds.feedburner.com/GirlWritesCode.

GirlWritesCode is moving to new digs; please join us.

2010-02-28T07:12:00.006-06:00

I use Blogger's FTP model, where my posts are published out to my webhost on Invisible City. Blogger is discontinuing that service, due to lack of use and to enable bigger and better things in their architecture. So I need to shuffle things around, and I hope that you will follow this blog to its new home.

I'll update GirlWritesCode.com to redirect to the new location, so if that's the url you've bookmarked, you're good to go.

I'll continue to cross-post at Los Techies. If that's your main means of keeping up with me, then... how are you reading this? ;-)

I'll have an RSS feed from the new location, but the url is going to change. It will be ~~http://girlwritescode.blogspot.com/atom.xml~~, I'm pretty sure. [Correction: http://www.girlwritescode.com/feeds/posts/default] I'll post a "we've landed" post from the new location, so you'll know when I've got it sorted.

I appreciate your readership. Everything I write, I write with you in mind. I hope you will follow this blog to its new location.

More Dogs and Bears and Chickens and Things: Invite your colleagues to Pablo's Fiesta

2010-02-07T16:32:00.000-06:00

If you work with developers who are women, please tell them about the Los Techies Open Space conference, coming up at the end of February. If you've attended an event like this in the past, you're already aware of some facts:

The Austin developer community is vibrant, engaged, and constantly striving to improve our craft. We've got a good thing going here.
The quality of the conversations and the value of the event far outstrip the price of admission; it would be a bargain at twice the price.
Women are way under-represented.

Early in my career, I wasn't tapped into the information channels that announce events like this. I didn't go because I just didn't know about them. My friend and colleague Josh Flanagan made a point of letting me know, and encouraging me to go, and showing that it was not only okay but right to ask my employer to send me to such things.

Attending conferences has made a huge difference in my growth as a developer and in my career. It brought me into the on-going conversation in the developer community. It exposed me to new practices and new technologies, which I brought back to the team. Please do the same favor for your women co-workers that Josh did for me: Tell them about Pablo's Fiesta and encourage them to sign up.

Bringing women into the mix brings new, diverse ideas into the conversation, new skillsets to the community, more role models for our kids. The conference will be improved by spicing up the guest list. Although I'm focusing on women here, reach out to any of your colleagues who "don't usually go to these things." New voices mean new synergy, which means more learning and more fun.

And you. Sign up, your own self. It'll be great.

If you have any questions about Pablo's Fiesta, or about whether you'd enjoy it, please feel free to post them here, and I'll get the answers for you.

Interface-Oriented Design - Book Review

2010-01-17T13:04:00.000-06:00

Ken Pugh's Interface-Oriented Design (Pragmatic Programmers) presents an approach to designing applications that focuses first on the interfaces, the places where pieces of the application interact. The interfaces here are not primarily user interfaces, but module-to-module interfaces and service interfaces, and the applications are not exclusively object-oriented. Pugh's proposed process is to identify use cases and test cases, determine the interfaces that will enable those use cases, then create tests and implementations for the interfaces.

The book is divided into three parts. The first explains the concepts and theory underlying an interface-focused approach to design. These concepts include real-world analogies which quickly provide context to the discussion; types of interfaces, such as stateless versus stateful, and procedural versus document; design concerns such as contracts, cohesiveness, and polymorphism; and the Asimov-inspired "three laws of interfaces," which specify the qualities of a well behaved implementation. Part two is brief and describes where interface-oriented design fits into the project lifecycle. Part three walks through three examples, from concept to design to implementation, and highlights the design patterns exhibited in those examples. The book concludes with a grab-bag appendix of topics that could have been better served by integration into the main text.

If your learning style is learn-by-doing, you might get more out of the book by reading Part Three before Part One. Part Three provides the "yeah, but what are we doin' here" skeleton onto which you can hang the theory that is explained in Part One. I find theory easier to digest and retain if I know which of my real-world, day-to-day experiences it applies to. You'll get that context if you flip the order in which you read it.

I picked up this book looking for best practices on providing and consuming remote interfaces, and it isn't that. Have you ever taken a sip of something you like, but because you were expecting a completely different flavor, it tasted off? I bumped into that dissonance here, so it was hard for me to get into the book. To appropriately prepare your palate, the flavor to anticipate from Interface-Oriented Design is a technique for thinking about a problem domain and its software solution by thinking about the places where responsibilities interact, analogous to the way that service-oriented architecture is a technique for thinking about software design.

An area where this book really shines is Pugh's deft use of real-world examples. In the first chapter, he introduces the process of ordering a pizza as a series of exchanges through a PizzaOrdering interface. The example is familiar, relatable, and practically identical across the United States (implementations vary, of course). Pugh then uses that example and expands upon it throughout the rest of the book, allowing us to fit new concepts into the model as it is refined. This worked better than if each new concept had been presented with a new example; the book gained a pedagogical momentum.

Many times during my reading, I asked myself whether the ideas were so fundamental and distilled as to shift my way of thinking, or so fundamental as to be mundane and trivial. Was this book raising the level of abstraction, like climbing a mountain to get a better view of the landscape, or just telling me no-duh stuff I already knew? Is its audience experienced developers looking to put terms and practices around habits they do instinctively, or is its audience beginners who need an introduction to methodical design? I still haven't decided. Will it affect my thinking? Probably. Not in ways that I can articulate and enumerate for you, but likely in subtle and profound ways that I may or may not notice as they occur. For yourself, I recommend checking out the table of contents (available from the Pragmatic Bookshelf) and see if it suits you.

Happy Hack-o-ween: Electronics and a microcontroller spice up the haunt

2009-11-08T10:35:00.000-06:00

Ah, Halloween, when a young woman's fancy turns to love. And zombies.

I had two personal requirements for the costume I would build this year:

It shall be spooky.
It shall blink.

I'll tell you about the final result, the electronics and the software that went into it, plus the techniques I used to achieve wearable electronics. I'll introduce you to the Arduino, an open-source microcontroller prototyping platform, which is an exhilarating tool/toy for making your software skills manifest in the physical world.

My husband and I have been teaching ourselves electronics. A few months ago, Dad taught me to solder. I recently read Syuzi Pakhchyan's excellent primer on wearable electronics and smart materials, Fashioning Technology. And I've been making things with my Arduino. All these ideas were swirling and combining in my head to inspire this year's Halloween project. Er, costume. Same difference.

What was I? I was a nightmare... the thing under your bed... the reason for your well developed sense of paranoia...

I sported a crop of writhing eyeballs erupting from my head. Each eyeball has an LED inside it, and they blink randomly and independently, until I trigger a hidden switch, which causes the blinky ones to go dark and two red eyes to pulse menacingly. In the Flickr photoset, you can see the construction process.

The Arduino Sketch

The term "Arduino" is overloaded to mean:

a particular chip and circuit board which you can buy or build;
the IDE in which you write programs for the chip;
the language, which is C-flavored;
fun.

Arduino programs are called sketches. Every sketch must contain two functions: setup (runs once) and loop (runs continuously). Here's my sketch, with extra explanatory comments, that blinks the six regular eyeballs and responds to the switch by pulsing the red eyeballs.

    1 #define SWITCH 8

    2 int ledPins[] = {2, 3, 4, 5, 6, 7};

    3 const int ledPinsCount = 6;

    4 int redEyePins[] = {10, 11};

    5 const int redEyePinsCount = 2;

    6 long durations[ledPinsCount];

    7 int ledStates[ledPinsCount];

    8 long previousTimes[ledPinsCount];

    9 int i;

   11 void setup()

   12 {

   13   pinMode(SWITCH, INPUT); //Specify the switch pin as an input.

   15   for (i = 0; i < redEyePinsCount; i++)

   16   {

   17     pinMode(redEyePins[i], OUTPUT); //Specify each red-eye LED pin as an output.

   18   }

   20   for(i = 0; i < ledPinsCount; i++)

   21   {

   22     pinMode(ledPins[i], OUTPUT); //Specify each regular LED pin as an output.

   23     ledStates[i] = random(1); //Randomly set the LEDs to on or off (1 or 0).

   24     durations[i] = GetRandomDuration(); //Define a random duration for each LED to stay in that state.

   25     previousTimes[i] = 0; //At time of setup, the "last time we changed" is at 0 milliseconds, the start of time.

   26   }

   27 }

   29 void loop()

   30 {

   31   if (digitalRead(SWITCH) == HIGH)

   32   {

   33     TurnOffLeds();

   34     PulseRedEyes();

   35   }

   36   else

   37   {

   38     for(i = 0; i < redEyePinsCount; i++)

   39     {

   40       digitalWrite(redEyePins[i], LOW); //Turn the red eyes all the way off.

   41     }

   43     for(i = 0; i < ledPinsCount; i++) //For each LED:

   44     {

   45       if (millis() - previousTimes[i] > durations[i])

   46       {

   47         ChangeLed(i); //If this one's duration is up, then flip it.

   48       }

   49     }

   50   }

   51 }

   53 void TurnOffLeds()

   54 {

   55   for(i = 0; i < ledPinsCount; i++)

   56   {

   57     digitalWrite(ledPins[i], LOW);

   58   }

   59 }

   61 void PulseRedEyes()

   62 {

   63   //Fade on, then off.

   64   int j;

   65   for(j = 0; j < 255; j+=5)

   66   {

   67     for(i = 0; i < redEyePinsCount; i++)

   68     {

   69       analogWrite(redEyePins[i], j);

   70       delay(10);

   71     }

   72   }

   73   for(j = 255; j > 0; j-=5)

   74   {

   75     for(i = 0; i < redEyePinsCount; i++)

   76     {

   77       analogWrite(redEyePins[i], j);

   78       delay(10);

   79     }

   80   }

   81 }

   83 void ChangeLed(int ledPin)

   84 {

   85   previousTimes[ledPin] = millis(); //Update the "last time we changed" to now.

   86   durations[ledPin] = GetRandomDuration(); //Give it a new random duration.

   87   ledStates[ledPin] = 1 - ledStates[ledPin]; //Flip the state between on and off.

   88   digitalWrite(ledPins[ledPin], ledStates[ledPin]); //Set the LED to that state.

   89 }

   91 long GetRandomDuration()

   92 {

   93   //Random number between 1 and 10, then multiplied by 400 to give it a detectable duration.

   94   return random(1, 10) * 400;

   95 }

I like the way the eyes blink independently. If they all flashed in unison, they would look like Christmas lights, and you would notice that two were "special" because they weren't flashing. Instead, the duration that any given eyeball is lit or dark constantly changes.

The blinking is managed by a collection of arrays. One array represents each of my LED pins, so that I can address them in a for loop. The three other arrays hold: the state (on/off) of each LED; the duration each LED should stay in that state; the reading from the millisecond counter when the LED last flipped its state. Each time the loop function executes, if the switch is not connected, then I look at each LED; if the difference between the current time and the time when it previously changed is greater than its duration, flip its state (from off to on, or from on to off), randomly assign it a new duration, and record "now" as the new "previously changed" time. If the switch is connected, then I make the red eyes fade on and fade off.

Fading with PWM

PWM (Pulse-Width Modulation) is a technique for making a digital component (one that turns on or off) simulate analog behavior (be a little bit on, and then a little bit more on). If you turn an LED off and on really quickly, you won't perceive the flickering, but it will look half as bright, because it is actually off for half the time. If you let it spend a little more time off than on, it will appear even dimmer. So by varying the width of the pulses, you can control how bright the LED looks.

The Arduino comes with built-in PWM functions; some pins are already set up to be PWM pins. If you plug an LED into one of the PWM pins, then you can write to it as if it were an analog component. That's why, in my sketch above, I set the brightness of the red eyes using analogWrite(), instead of digitalWrite(). My for loop increments the counter j from 0 to 255, and sets the brightness of both red eyes to the value of j. The Arduino takes care of (imperceptibly) flickering the LEDs with the right ratio of on-time and off-time to achieve a j amount of brightness. So the eyes get gradually brighter, then gradually dimmer. (Then control returns to the main loop function, but if my switch is still connected, the red eyes will throb again.)

Snaps: Wearable Plugs

A metal sewable snap is like a plug for your clothing, an interface between the world of textiles and the world of wires. This is handy when you need the electronics to be separate while you are getting into the clothing, or if you want to wash the clothing. My Arduino hung out at the base of my neck, to be near the LEDs on my head but hidden underneath my wig, but my control switch was near my hip. I could have run a wire down to the switch, but conductive thread was more subtle and more comfortable.

To complete the connection, I soldered a short wire to one side of the snap. That wire plugged into a pin on the Arduino. The conductive thread ran from the switch at my hip up to the back of my dress near the Arduino, and I sewed that conductive thread to the other half of the snap. When the two halves are snapped together, the wire and the thread make a complete connection, as if they were one continuous wire.

I had two threads (going out to the switch and back), so I encased them each in a bias tape tube, to prevent them from touching each other and shorting out.

I've been saying "switch," but actually, I simplified at the 11th hour. I tied each thread around a safety pin, and stuck the pins to my dress. When the safety pins touched each other, they completed the circuit, which the Arduino sketch interpreted as triggering the switch—cue red-eye glare.

What's Next

Soldering and sewing are both liberating skills to possess—they free up your creativity to make wilder and more integrated stuff. If you are currently proficient with only one, ask around and see if you can find a buddy who's good at the other, and teach each other.

The Arduino comes with a great community of hackers and makers, lots of people to learn from and collaborate with. Definitely check it out. There is lots of fun to be had, and blinking LEDs is the barest beginning of what it can do.

Refactoring Dinner: Interfaces instead of Inheritance

2009-10-13T21:24:00.002-05:00

Last time, in Cooking Up a Good Template Method, I had a template method cooking our dinner. An abstract base class defined the template—the high level steps for preparing a one-skillet dinner—and a derived class provided the implementation for those steps. I'm currently reading Ken Pugh's Interface Oriented Design (more on that after I finish the book), and it got me thinking of a way to change the design to use interfaces instead of inheritance.

I think there's value in this refactoring because it allows future flexibility and testability. Let's stroll through it, and I welcome your thoughts about how (and whether) this improves the code.

Previously, we had a base class SkilletDinner, which was extended by variants on that theme, such as chicken with onions and bell peppers or the FancyBaconPankoDinner. (If I've learned one thing from my readership, it is that blog posts should mention bacon. Mm, crispy bacon.) As the first step in the refactoring, I'll create an interface, ISkilletCookable that provides the same methods that were previously abstract methods in SkilletDinner. By naming convention, the interface is prefixed with 'I' and is an adjective describing how it can be used (-able).

    4   public interface ISkilletCookable

    5   {

    6     void HeatFat();

    7     void SauteSavoryRoot();

    8     void SauteProtein();

    9     void SauteVegetables();

   10     void AddSauceAndGarnish();

   11   }

Next, I'll create a SkilletDinner constructor that accepts an ISkilletCookable, and change the SkilletDinner's Cook() method to ask that cookable to do the work. SkilletDinner no longer needs to be abstract.

    5   public class SkilletDinner

    6   {

    7     private readonly ISkilletCookable cookable;

    9     public SkilletDinner(ISkilletCookable cookable)

   10     {

   11       this.cookable = cookable;

   12     }

   14     public void Cook()

   15     {

   16       cookable.HeatFat();

   17       cookable.SauteSavoryRoot();

   18       cookable.SauteProtein();

   19       cookable.SauteVegetables();

   20       cookable.AddSauceAndGarnish();

   21     }

   22   }

Then, FancyBaconPankoDinner implements ISkilletCookable and provides implementations for each of the methods that will be called by the Cook() method.

The first benefit from this refactoring is flexibility. While FancyBaconPankoDinner could not have inherited multiple classes (no multiple inheritance in C#), it can implement multiple interfaces. For example, it could also implement the IShoppable interface, thereby providing a ListIngredients() method that would let me include it in my grocery list.

This refactoring also makes it easier for me to test the quality and completeness of my template method. I can verify—does it cover all of the requisite steps for cooking a skillet dinner?—by creating behavior-verifying tests that assess the SkilletDinner's interactions with the ISkilletCookable interface. When I'm writing unit tests for the SkilletDinner class, I want to test its behavior because the behavior is what's important.

To forestall objections, I tried writing a test around the old version, creating my own mock class that extends the old abstract SkilletDinner. It got pretty lengthy.

    4   public class SkilletDinnerSpecs

    5   {

    6     [TestFixture]

    7     public class When_told_to_cook

    8     {

    9       const string heatFatMethod = "HeatFat";

   10       const string sauteSavoryRootMethod = "SauteSavoryRoot";

   11       const string sauteProteinMethod = "SauteProtein";

   12       const string sauteVegetablesMethod = "SauteVegetables";

   13       const string addFinishingTouchesMethod = "AddFinishingTouches";

   15       [Test]

   16       public void Should_follow_dinner_preparation_steps_in_order()

   17       {

   18         var systemUnderTest = new MockSkilletDinner();

   20         var expectedMethodCalls = new List<string>();

   21         expectedMethodCalls.Add(heatFatMethod);

   22         expectedMethodCalls.Add(sauteSavoryRootMethod);

   23         expectedMethodCalls.Add(sauteProteinMethod);

   24         expectedMethodCalls.Add(sauteVegetablesMethod);

   25         expectedMethodCalls.Add(addFinishingTouchesMethod);

   27         systemUnderTest.Cook();

   29         Assert.AreEqual(expectedMethodCalls.Count, systemUnderTest.CalledMethods.Count, "Expected number of called methods did not equal actual.");

   31         for (int i = 0; i < expectedMethodCalls.Count; i++)

   32         {

   33           Assert.AreEqual(expectedMethodCalls[i], systemUnderTest.CalledMethods[i]);

   34         }

   35       }

   37       private class MockSkilletDinner : SkilletDinner

   38       {

   39         public readonly List<string> CalledMethods = new List<string>();

   41         protected override void HeatFat()

   42         {

   43           CalledMethods.Add(heatFatMethod);

   44         }

   46         protected override void SauteSavoryRoot()

   47         {

   48           CalledMethods.Add(sauteSavoryRootMethod);

   49         }

   51         protected override void SauteProtein()

   52         {

   53           CalledMethods.Add(sauteProteinMethod);

   54         }

   56         protected override void SauteVegetables()

   57         {

   58           CalledMethods.Add(sauteVegetablesMethod);

   59         }

   61         protected override void AddFinishingTouches()

   62         {

   63           CalledMethods.Add(addFinishingTouchesMethod);

   64         }

   65       }

   66     }

   67   }

In the new design, I can mock the ISkilletCookable interface with a mocking framework like Rhino.Mocks. The interface is easy to mock because interfaces, being the epitome of abstractions, readily lend themselves to being replaced by faked implementations. Rhino.Mocks takes care of recording and verifying which methods were called.

    7   public class SkilletDinnerSpecs

    8   {

    9     [TestFixture]

   10     public class When_told_to_cook

   11     {

   12       [Test]

   13       public void Should_follow_dinner_preparation_steps_in_order()

   14       {

   15         var mocks = new MockRepository();

   16         var cookable = mocks.StrictMock<ISkilletCookable>();

   17         var systemUnderTest = new SkilletDinner(cookable);

   19         using (mocks.Record())

   20         {

   21           using (mocks.Ordered())

   22           {

   23             cookable.HeatFat();

   24             cookable.SauteSavoryRoot();

   25             cookable.SauteProtein();

   26             cookable.SauteVegetables();

   27             cookable.AddSauceAndGarnish();

   28           }

   29         }

   30         using (mocks.Playback())

   31         {

   32           systemUnderTest.Cook();

   33         }

   34       }

   35     }

   36   }

The test relies on Rhino.Mocks to create a mock implementation of ISkilletCookable, and then verifies that the system under test, the SkilletDinner, interacts correctly with ISkilletCookable by telling it what steps to do in what order.

That test is quite cognizant of the inner workings of the SkilletDinner.Cook() method, but that's specifically what I'm unit testing: Does the template method do the right steps? I don't mind how the steps are done, but you have to start the onions before you add the meat, or else the onions won't caramelize and flavor the oil.

By the way, if you had previously found the learning curve for Rhino.Mocks' record/playback model too steep a hill to climb (or to convince your teammates to climb), check out Rhino.Mocks 3.5's arrange-act-assert style. It creates more readable tests, putting statements in a more intuitive order. I really like it. I could not, however, use it here because I have not found a way to enforce ordering of the expectations (i.e., to assert that method A was called before B, and to fail if B was called before A) in A-A-A-style. So we have a record/playback test, instead.

Here's a summary of the refactoring. I extracted an interface, ISkilletCookable, and composed SkilletDinner with an instance of that interface, liberating us from class inheritance. Because SkilletDinner is now given the worker it depends on (via dependency injection), I can give it a fake worker in my tests, so that my unit tests don't need to perform the time- and resource-consuming operation of firing up the stove. And I managed to write another blog post that mentions bacon. Mm, bacon.

Cooking Up a Good Template Method

2009-08-29T12:18:00.004-05:00

The software concept of "raising the level of abstraction" has improved my skill and creativity in cooking, by teaching me to think about recipe components in terms of their properties and functions. Practicing abstraction-raising in cooking feeds back to help me with coding; for example, keeping me from going astray the other day with the Template Method pattern. This post is more about coding than cooking. The cooking's a metaphor. (The cake is a lie.)

Abstract Cooking
My skill with cooking grew from rote recipe following to intuitive creation when I started to think of it in terms borrowed from software: raising the level of abstraction.

Consider a week-night skillet dinner. If I told you to heat canola oil in a cast-iron skillet, saute slices of onion and chunks of chicken seasoned with salt and pepper, and toss in bell peppers cut into strips, you could probably follow along and make exactly that. But that's pretty limiting. If instead I described the process as using a fat to conduct heat for sauteing a savory root, a seasoned protein, and some vegetables, then you could use that as a template, and make a week of dinners without repeating yourself.

Let's dive into that step of using a fat for conduction, because it is a cool and useful bit of food science. To cook, you need to get heat onto food. The medium can be air, liquid, or fat. Each creates different results, hence the terms baking, boiling, and frying. When you toss cut-up bits of food in a skillet with oil and repeatedly jostle them, you're sauteing ("saute" means "to jump"), and that oil is playing the role of the fat, which is conducting the heat. If you'll pardon the metaphor, CanolaOil implements the IFat interface.

It's useful to think of cooking this way, because if you know the properties of the various cooking fats, you can choose the right IFat implementation for the job. Canola oil is heart-healthy and stands up well to stove-top heat. Olive oil has wonderful health benefits, a bold flavor, and an intriguing green color, but those attributes are pretty much obliterated by heat, so save your expensive EVOO for raw applications like salads and dips. Butter makes everything taste better, browns up beautifully, but is harder on the heart and will burn at a low temperature; temper it with an oil like canola to keep it from burning. Peanut oil stands up to heat like a champ, so it's popular for deep frying. Armed with this kind of knowledge, I don't need to check a recipe when I'm cooking; I just think about what I'm trying to accomplish, and choose the right implementation.

Pam Anderson's How to Cook Without a Book got me thinking about food this way, and Harold McGee's On Food and Cooking provides a feast of food geekery to fill in all the particulars.

Template Coding
Thinking about food this way, raising the level of abstraction, guides my thinking about code. My meal preparation follows the Template Method pattern, as does a class my teammate and I needed to modify recently.

In this example, our application sends instructions to various external systems. The specifics of how those systems like to hold their conversations vary between systems. However, the series of steps, when phrased in our core business terms, remain the same. You do A, then you do B, then you do C, in whatever way a particular instance likes to do A, B, and C.

Here's my class with its template method, translated back to the dinner metaphor:

    3     public abstract class SkilletDinner
    4     {
    5         public void Cook()
    6         {
    7             HeatFat();
    8             SauteSavoryRoot();
    9             SauteProtein();
   10             SauteVegetables();
   11         }
   12 
   13         protected abstract void HeatFat();
   14         protected abstract void SauteSavoryRoot();
   15         protected abstract void SauteProtein();
   16         protected abstract void SauteVegetables();
   17     }

But lo, I encountered an external system that needed to do one extra little thing. I needed a special step, just for that one instance. Like dinner the other night, where the vegetable was asparagus, the fat was bacon (oh ho!), and the final step was to toss some panko breadcrumbs into the pan to brown and toast and soak up the bacony love.

How do I extend my template method to accommodate an instance-specific step?

One idea that floated by was to make the method virtual, so that we could override it in our special instance. But we still wanted the rest of the steps, so we'd have to copy the whole method into the new instance, just to add a few lines. Also, anybody else could override that template, too, so that when they were told to do A, B, and C, they could totally fib and do nothing of the sort.

    3     public abstract class SkilletDinner
    4     {
    5         public virtual void Cook()
    6         {
    7             //Note: The Cook template method is now virtual,
    8             //and can be overridden in deriving classes. 
    9             //That's not good.
   10             HeatFat();
   11             SauteSavoryRoot();
   12             SauteProtein();
   13             SauteVegetables();
   14         }
   15         protected abstract void HeatFat();
   16         protected abstract void SauteSavoryRoot();
   17         protected abstract void SauteProtein();
   18         protected abstract void SauteVegetables();
   19     }
   20 
   21     public class LazyDinner : SkilletDinner
   22     {
   23         public override void Cook()
   24         {
   25             OrderPizza();
   26             //We're overriding the template and *cheating*!
   27             //Although, if it's Austin's Pizza, 
   28             //maybe that's okay...
   29         }
   30 
   31         private void OrderPizza()
   32         {
   33             //With extra garlic!
   34         }
   35 
   36         protected override void HeatFat() { }
   37         protected override void SauteSavoryRoot() { }
   38         protected override void SauteProtein() { }
   39         protected override void SauteVegetables() { }
   40     }

That LazyDinner class isn't really a SkilletDinner at all; its behavior is completely different. No, that option flouts the whole point of the Template Method pattern.

Our better idea was to make one small change to the template method, adding an extension point. That is, a call to a virtual method which in the base implementation does nothing, and can be overridden and told to do stuff in specific cases.

Back to dinner:

    3     public abstract class SkilletDinner
    4     {
    5         public void Cook()
    6         {
    7             HeatFat();
    8             SauteSavoryRoot();
    9             SauteProtein();
   10             SauteVegetables();
   11             AddFinishingTouches(); //Here's the hook.
   12         }
   13 
   14         protected virtual void AddFinishingTouches()
   15         {
   16             //By default, do nothing.
   17         }
   18 
   19         protected abstract void HeatFat();
   20         protected abstract void SauteSavoryRoot();
   21         protected abstract void SauteProtein();
   22         protected abstract void SauteVegetables();
   23     }
   24 
   25     public class FancyBaconPankoDinner : SkilletDinner
   26     {
   27         protected override void AddFinishingTouches()
   28         {
   29             //In this case, override this extensibility hook:
   30             ToastBreadcrumbs();
   31         }
   32 
   33         private void ToastBreadcrumbs()
   34         {
   35             //Toss in the bacon fat; keep 'em moving.
   36         }
   37 
   38         protected override void HeatFat()
   39         {
   40             //Cook bacon, set aside, drain off some fat.
   41         }
   42 
   43         protected override void SauteSavoryRoot()
   44         {
   45             //Minced garlic, until soft but before browning
   46         }
   47 
   48         protected override void SauteProtein()
   49         {
   50             //How about... tofu that tastes like bacon?
   51         }
   52 
   53         protected override void SauteVegetables()
   54         {
   55             //Asparagus, cut into sections. 
   56             //Make it bright green and a little crispy.
   57         }
   58     }

This maintains the contract of the template method, while allowing for special cases. With the right extensibility hooks in place, my dinner preparation happily follows the Open-Closed Principle—open for extension, but closed for modification.

I enjoy the way my various hobbies feed into and reflect upon each other. I hope this post has given you some useful insight into the Template Method pattern, or dinner preparation, or both. Look for synergies amongst your own varied interests; it can be the springboard for some truly breakthrough ideas.

Mmm, bacon...

Inconvenient Accessibility Makes Self-Documenting Code

2009-06-20T07:19:00.000-05:00

Intentional use of access modifiers (public, private, etc.) is like a clear memo to your team. This came up during Steve Bohlen's Virtual Alt.Net talk on domain-driven design.

Steve explained the distinction between Entity objects, which have a unique identity independent of their properties (Even when I change my name, I'm still me.), and Value objects, which are defined by their properties (If you change the house number in an address, you have a new address.). When dealing with Entities, code should not be able to change the unique id—that would be like someone claiming your social security number and thereby becoming you. Therefore, Entity classes should have private setters for their unique identifiers.

A meeting attendee asked why, since this gets inconvenient when you're creating an object based on a record fetched from the persistence repository. It's a big pain; why bother? The analogy I would offer is this. When you're defining a class to represent an Entity in your business domain, you know it's an Entity. You intend for it to behave and be treated like an Entity. You don't want any of your teammates setting its unique id in their code. So you send them an email: "Don't set Person.UniqueId, okay?" Uh hunh. How well is that going to work over time?

Instead, if you simply don't provide a public accessor to the UniqueId property, your teammates will get the message loud and clear. Granted, someone could edit the code and change the accessibility, but the fact that he or she needs to is a flashing neon sign saying "Stop. Think. Are you barking up the wrong tree?" You've made your code communicative. Its structure conveys your intent. No need for comments; this is an example of self-documenting code.

Giving Mono to my Husband

2009-05-31T15:37:00.004-05:00

Holy crossed-platforms, Batman! How did I not know about Mono, the free, open-source framework that will run .NET applications on Linux and Mac OS X?

Not to get too personal, but I'm part of a mixed marriage: I run Windows and develop primarily in C#; my husband runs OS X and is not (actively) a programmer. Through love and mutual respect, we make it work. But what we have so far not been able to make work is my writing handy utilities and toys that he can use on his laptop.

I learned about Mono in Rod Paddock's intro to the May/June issue of CoDe Magazine. Then I came home, had Jon install Mono on his Mac, and gave him a quick little console app I'd written in C#. It ran like a charm. A WinForms app with one button and a popup message also ran, looking distinctly X11-y.

This is super exciting for us. We've been talking about a card-game playtest simulator, to help with his creation of card games. (Jon posts one free board game a month and has a few upcoming commercial releases.) That process usually involves a significant investment in card stock and time with the paper cutter, just to see how hands of cards come together and move through the game. A simulator would help him to vet the first and maybe second drafts of the cards without printing them out. Now that I know I can build something he'll be easily able to run, it's time to start designing!

Got the 0000FFs

2009-04-25T11:08:00.001-05:00

Given up on attaching meaning to those three- or six-character codes that define colors in HTML and CSS? Sure, you can use an online color picker, but let me give you a nuts-and-bolts explanation of what they mean. This info is worth having because:

It's a time-saver. If you want to make a color a little more blue, or a little less saturated, you can do the math in your head and take care of it right there in your editor.
It gives you more options. If you find a cracking color combo in the Color Index, but it's given only in RGB values, you can convert it to HTML-ready values using just math.
It's satisfying. Don't you prefer knowing how something works, instead of just how to work with it?
It will be diverting. There will be stories, you know me.

Two experiences in my childhood laid the foundation for my understanding of hex color codes, so I will share them with you. (See? Stories.)

When I was very young, I learned that the three primary colors are red, yellow, and blue, and when you mixed them together you got, well, mud, but theoretically black. That's true for pigments (paint and ink; think magazines and newspapers), and if you're going to be pedantic, those pigment primary colors are properly called magenta, yellow, and cyan. (Add blacK and you have CMYK, the other color scheme you'll see mentioned in design books.) But it's a whole 'nother ball game when you are mixing light instead of pigment, and computer monitors are big light bulbs.

My seventh-grade science teacher, Mr. Saeger, created an excellent demonstration that I still think of when I'm mixing up hex color codes. He set up the overhead projector. He placed a square of red cellophane on the projector, and it threw a red square of color up on the wall. Sure. Then he added a piece of green cellophane, and the area where they overlapped was... yellow? That's curious. Last he added a piece of blue, and the intersection of all three was white. It blew my mind.

If you can replicate this effect (shine a light through overlapping colored plastics), it's a great science experiment to share with your kids. It will help you remember the mixing of light colors with the same intuition you have for mixing pigments. And it's cool.

The second formative experience from my youth was working the stage lights in my high school theater. Hanging above the stage were three rows of lights; the lights alternated amongst white, yellow, red, and blue, and were controlled by a huge wall of levers backstage. Big, creaky, ancient things, that really let you know you were working the lights. I had to crouch and get my shoulder under them to move the big ones.

Picture them: Four rows of colored levers, corresponding to each color of light out over the stage. Each lever controlled a light. Down was off, and as you pushed the lever up, the light would gradually brighten. A big handle at the end of a row would move all the levers of that color, so you could, for example, bring up all the whites in unison. You could slowly turn down the yellows over the course of a scene while a teammate pushed up the reds, and make a sunset. You could push all the colors up to make the light full and cheery (and make the stage hotter than a tanning booth), or pull them all down to plunge the stage into darkness at the dramatic conclusion of Act I.

Levers... lights... hex codes, here we go.

Light is mixed from red, green, and blue. (Remember the order: RGB, RGB, RGB.) Computers like to count not from 1 to 100, but from 0 to 255. Think of 0 as off, with the lever all the way down, and 255 as on, with the lever all the way up. To make yellow, you need a lot of red and a lot of green, and no blue, so R = 255, G = 255, and B = 0. To make a paler yellow, you want to bring it closer to white. White is all three on at maximum; therefore you need to turn up the blue. Maybe R = 255, G = 255, and B = 153. To make it more orangey, you'd back off the green. And so forth.

So we have three levers. A hex color code has three pairs of characters. That yellow would be #FFFF00. Put another way: FF, FF, 00. It's the same three RGB values, but in base 16 instead of base 10. 255 in base 10 becomes FF in base 16. Counting in base 16 is like counting in base 10, if you had 6 extra fingers. 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F, 10.

The Math Bits site gives a visual explanation of how to convert from base 10 to other bases. Also, you can use the calculator on your computer. In Windows, set the calculator to Scientific mode in the View menu, make sure the "Dec" radio button is marked, type in your base-10 number, then switch to the "Hex" radio button and read the converted value. But usually when I'm writing HTML, I just need to nudge a color a little, not do a whole decimal-to-hexadecimal conversion. So it is sufficient to know that all zeroes is all black, all Fs is all white, CC is more "on" than 99, and EE is just a teeny bit less than full on.

CSS also permits three-character color codes. The same color-mixing is happening there, it's just a shortcut that doubles each character for you. So #ca9 is equivalent to #CCAA99.

Putting this into practice...

#FFFFFF	Turning all three levers full on makes white.
#CCCCCC	Backing them off a little, but keeping them all equal, makes gray.
#000000	Turning them all off: Black.
#FF0000	Red on and the rest off makes red.
#990000	Turning down the red, so that it moves closer to black, makes a darker red.
#FF6666	Turning up the others, so that the whole mix moves closer to white but has more red than anything else, makes pink ("Lightish red!").
#FFFF00	Red plus green (when mixing light) make yellow.
#FF9900	Keep the red, but reduce the green, to make orange.
#00FFFF	Green and blue make teal.
#FF00FF	Red and blue make purple.

So there you have it: An explanation of hex color codes by way of my seventh-grade science class and my high school drama—er, drama department. Right.

The Null Object Pattern: When a slacker is just what you need

2009-03-02T18:35:00.005-06:00

I had a challenge that was neatly solved by the Null Object pattern. I'd like to share it with you, so that I can explore the idea and provide a practical example.

Simplifying a bit, I have a Person object, and I need to fill it with details retrieved from an external system. When I started looking at the code, the call to look up the Person attributes took a Person as a passed-in parameter and modified it. That struck me as bad behavior ("Hey! I gave you that so you could use it, but I didn't expect you to change it. Sheesh."). I thought it would be more honest for the method to return information, which the controlling class could use to update the Person object if it chose to.

Let me name the players, to make this easier to follow. I have a class coordinating activities that, in our business context, is called a Translator. I created a Client that makes the actual calls to the external system. Before the refactoring, the Translator would call Client.Lookup(Person). The Client would create a message to the external system, get back a response, and use it to set attributes in the Person.

I changed Client.Lookup so that it does not change the Person, and instead returns a Response that contains the needed attributes. But if the external system did not have any info to return, should Lookup return null, throw an exception, ...?

Usually the most appropriate answer to this question is to throw an exception. If no info means you're in an invalid state or an unknown state, then it is not safe to continue, and the code should throw. In this case, though, we could continue. We didn't require the info coming back from the external system; it was just handy if available.

So I return null? But that means every time I call Client.Lookup, I have to check whether the Response is null before I use it. And so does anyone else who might be calling it in the future. It seems disingenuous for a method to say, "I'll give you a Response, but I might actually give you an empty bag. I hope you've guessed I might do that and planned accordingly."

   12 public void DoFancyBusinessSteps(Person person)
   13 {
   14     Response response = client.Lookup(person);
   15     if (response != null)
   16     {
   17         person.Address = response.Address;
   18         person.ExternalSystemId = response.ExternalSystemId;
   19     }
   20     //More stuff based on the Person...
   21 }

I'd rather return an object that is safe to use, regardless of what answer we got from the external system, and is helpful if we received useful info. This is the Null Object pattern.

I created an IResponse interface that exposes one method, Update(Person). Next I created two implementations of that interface, a Response and a NoDataResponse.

   12 public void DoFancyBusinessSteps(Person person)
   13 {
   14     IResponse response = client.Lookup(person);
   15     response.Update(person);
   16 
   17     //More stuff based on the Person...
   18 }

Response.Update uses its fields to set properties on the Person (with a method name that clearly states it is doing so). NoDataResponse.Update quietly does nothing. This allows the Translator to ask the Client to look up info about the Person, and ask the resulting Response to update the Person.

   21 public class NoDataResponse : IResponse
   22 {
   23     public void Update(Person person)
   24     {
   25     }
   26 }

I like it. As with all good tools, it's prudent not to over-use it. If quietly doing nothing would leave the Person object in a bad state, so that it blew up or corrupted data when you tried to use it later, then don't use the Null Object pattern. Throw an exception instead. The Null Object pattern is handy when you want to return an object that can do stuff in some conditions and will be harmless in other conditions.

Follow-up to the Retrospectives Workshop

2009-02-24T16:59:00.004-06:00

My co-facilitator Suzy wrote up her reflections from the AgileAustin retrospectives workshop, where she shares more of the great insights that came from the participants.

Retrospectives: Collaborative Improvement

2009-02-21T17:08:00.003-06:00

Suzy Bates and I facilitated an AgileAustin workshop this morning called "Cheaper Than an Off-Site: How to hold effective retrospectives that improve team collaboration and performance." It was absolutely a blast, from planning through delivery. A benefit I didn't anticipate (but should have) is that I learned a lot, myself. I'll share some of those epiphanies here.

If you were to ask me what one thing a team could do to improve its delivery of great software on a predictable schedule, I would say: hold effective retrospectives. A retrospective is a regularly recurring discussion where the team reflects on how they work together, and what they will change in order to get better. The end of a sprint, right after the demo, is a good time for this.

We presented the following as the key ideas:

Safety
Diversity of viewpoints
Collective ownership
Structured discussion

Being a facilitator for the workshop was a bunch of fun. Collaborating with Suzy was excellent—meshing our two approaches really enhanced the content, as I brought the philosophy and she brought the practical hands-on exercises, and we kept each other moving and making progress on our preparations. If you're tempted to lead a workshop but daunted, find a teammate.

The audience participation was even richer than I'd hoped. People enthusiastically contributed, leapt into the exercises with gusto, and shared some striking insights. I learned neat stuff. Here are some highlights:

Rotate who holds the role of retrospective leader (or sponsor). That brings fresh ideas and spreads the sense of shared ownership.

When a team member expresses dissatisfaction (for example, through a team satisfaction histogram), sometimes it is appropriate to acknowledge it without delving into why and root cause and solutions. If team safety means I can say how I feel and that's okay, then I should be able to say how I feel without getting interrogated about why I feel that way.

A bunch of "went well" items without any "needs fixing" items might indicate a lack of team safety. In today's exercise, our sprint teams barely knew each other, so they wanted to be polite, and so they were very positive in their reflections. When you're comfortable with your team and trust them, it becomes easier to talk about areas for improvement. I'd view a series of "everything was great" sessions as indicative of a lurking problem.

Affirmative Inquiry is a philosophy/strategy worth looking into. It replaces, for example, the negative "why is this broken" by changing it into a positive "what was successful in the past that we could apply here."

Book recommendation for Jim Highsmith's work (probably Agile Project Management?).

If you attended the workshop: Thanks! It rocked. If you weren't able to, keep an eye out for future AgileAustin workshops. They're announced on the AgileAustin email list, so sign up for that. If you don't live in Austin, well... nanny nanny boo boo.

Quantifying Benefits on Refactoring Work

2009-01-11T13:05:00.003-06:00

When last we talked about estimating and prioritizing code maintenance, we'd left it as an exercise for the reader to devise a method to compare the relative size of the benefit from two different refactorings. In other words, you can work on A or B; which one is likely to give a greater benefit? I've had an idea for how to do this. It even includes some satisfying math.

Start with the premise that, when estimating the size of effort, it is sufficient—nay, preferable—to compare values in an abstract unit ("story points") that does not map directly to any real-world concept (such as "hours"). When you try to estimate effort in a real-world unit, people get distracted by (hung up on) the wrong details. Better to use an abstract unit that lets you compare the relative sizes of two efforts. Then you can prioritize them ("Let's do the smaller one."), and over time you develop a predictive measure of how many units your team can deliver. Can we create a similarly abstract yet useful unit for comparing benefits?

You undertake a refactoring because you want to make the code better. The benefit from this work comprises two pieces: how much you're going to improve an area of the codebase, and how important that area is. Your impact will be made up of how much "betterness" you can impart, and how much the betterness will matter.

You've probably had a similar experience: You find an area of the code that makes you frankly itch to improve it. You could dramatically increase its beauty. But it's not really used in very many places, and business needs hardly ever drive you to change it, so its beauty or lack thereof is actually rather insignificant. On the other hand, there's a class that makes you queasy every time you have to interact with it, but it's used everywhere, so changing it would be a huge, risky undertaking. It stays ugly, despite being so important.

There are a number of intuitive and emotional influences in those decisions, and they interact with each other in additive and multiplicative ways. This is a good place to apply some rigor, to get the emotions out of the way and compare options more objectively. You apply a similar rigor when you tackle a difficult decision by actually writing down the pros and cons in two columns on a piece of paper, so that you can see how the two sides stack up. So let's apply that to comparing the possible benefits from two refactorings. We only have time to do one, so we're trying to decide which one to do.

Consider a questionnaire, with pairs of questions, asking about what the code might be like after you're done.

Future proofing:

How much easier will it be to change it the next time?

How often do we get asked to change this area?

Regression proofing:

How much better will our test suite be able to prevent defects in this area?

How business-critical is it that we don't introduce defects in this area?

Avoiding risk:

How likely are we to succeed without creating problems?

How tolerant is our business of risk in this area?

Improving satisfaction and increasing velocity:

How likely are we to reduce tech support incidents by this work?

How many of our tech support incidents can be attributed to this area?

And so on, with questions that are specific to your own team. Collaborate with your team to create the questions, so that they represent the team's decisions. Note how a pair of questions covers how much improvement and how much that improvement will matter. Also see that for each question, a more emphatic answer is a good thing. For example, the avoiding-risk question asks how likely we are to succeed, not how risky the task is. Questions are phrased so that, the more you say "Yes, a lot," the more that's an endorsement in favor.

Now, depending on your bent, this next bit will remind you either of a prioritization matrix or a Cosmo quiz. Nevertheless, for each question in your questionnaire, answer a 1, 3, or 5, to represent "barely," "some," "a lot." Then multiply the coordinated a's and b's and add those up: (1a * 1b) + (2a * 2b) + (3a * 3b)... In this way, you represent the multiplicative relationship between How Much Better and How Much Does It Matter.

We need a unit for these scores. I'm thinking "bunits" (BYOO-nits) because they are a unit of benefit and of beauty. So if you have two refactoring tasks on the table during your sprint planning, and Refactoring A has an effort of 13 story points and a benefit of 17 bunits, while Refactoring B has an effort of 8 story points and 23 bunits, you can lean towards choosing Refactoring B. As with all matrices of this type, if that decision completely flouts your intuition, then discuss it with your team—maybe your intuition can be calmed, or maybe the questionnaire is failing to cover an important aspect of your work and needs some additional questions.

The real benefit of refactoring is proven only over time. Keep previous bunit estimates in mind and use those in your comparisons and trade-offs when selecting refactorings to undertake. Add this technique as another tool to help you understand the parameters of your decision, but never to override your own good sense.

This is a technique for quantifying the benefit of work that does not have a direct dollar ROI. Why quantify benefit, especially in a unit that has no analog in the real world? Two reasons. First, if you're going to prioritize your to-do list, every item needs some sense of effort and some sense of reward. It just makes sense to do easy things with lots of benefit before hard things that barely matter. Second, asking yourself questions like the above imparts rigor to your decision-making process. We are seekers of beauty, and want desperately to clean up whatever icky thing we looked at most recently. Surveying the choices and comparing relative benefits prods us to make sound business decisions, instead of scratching an itch.