personal, process comments edit

If you’re writing a programming article or an email to your team, many times you’ll probably try to provide an example code snippet to illustrate the point you’re trying to make. The problem is, regardless of the example, you will most likely fall into one of these losing traps:

THE PROSE EXAMPLE

This example is where you try to describe the code in a paragraph like this one, in natural language.

When registering a component for dependency injection, be aware of the lifetime you choose for the component. Choosing the wrong lifetime may mean the component lives longer than you intend. For example, if you have a component that keeps state information based on the current incoming request, you don’t want to keep it around as a singleton.

The trap here is that many people stop reading about five words in and don’t pay attention to what you’re trying to say. TL;DR. Even if the example you’re trying to explain requires some additional detail, attention spans wane and… you’re not even reading this anymore, are you?

THE FOOBAR EXAMPLE

This example is intentionally obscured from a naming perspective so that people ignore the names and focus on what the code is actually doing. The names “foo” and “bar” are commonly used as placeholders. For example, if you wanted to demonstrate automatically implemented properties in C#, you might show a class like this:

public class Foo
{
  public string Bar { get; set; }
}

It’s shorter and more direct than prose, which will keep those ADD engineers at bay… but the trap with this one is that you’ll get people who can’t work through the concepts because of the ambiguous naming, or they can’t figure out where the concept applies because the example was not concrete enough to make sense.

To address this, you get into…

THE IMPRECISE CONCRETE EXAMPLE

This is when you want to show a quick example of something but you don’t want people to get hung up on the names for things. The implementation really isn’t important, it’s just an example. Like if you wanted to demonstrate numeric parsing…

public class Address
{
  public int PostalCode { get; private set; }

  public void ParseAndSetPostalCode(string input)
  {
    this.PostalCode = Int32.Parse(input);
  }
}

The good part is that it’s more concrete, so the folks who couldn’t figure out the Foobar example can see where a concept might be used. On the other hand, with imprecise examples you inevitably get trapped by people complaining about the design of the code. “Are you sure you wouldn’t want to check for null first? What if the input isn’t a numeric string?”

You see this a lot with some of the quick demos given at presentations - the code isn’t 100% complete and tested (because it’s a demo) but people do the Monday-morning-quarterback thing and wonder why that wasn’t included.

So, that leads you to…

THE PRECISE CONCRETE EXAMPLE

This type of example is when you provide some code where all the details are there. It addresses the shortcomings in the imprecise example, but comes with it’s own issues. Like if you were demonstrating how one might use ACLs in the filesystem…

using System;
using System.IO;
using System.Security.AccessControl;

namespace SomeNamespace
{
  public static class FileInfoExtensions
  {
    public static void AllowFullControl(this FileInfo file, string username)
    {
      if (file == null)
      {
        throw new ArgumentNullException("file");
      }
      if (username == null)
      {
        throw new ArgumentNullException("username");
      }
      if (username.Length == 0)
      {
        throw new ArgumentException("Username may not be empty.", "username");
      }
      if (!file.Exists)
      {
        throw new FileNotFoundException(String.Format("Unable to find file {0}", file.FullName), file.FullName);
      }
      var acl = file.GetAccessControl();
      var rule = new FileSystemAccessRule(username, FileSystemRights.FullControl, AccessControlType.Allow);
      acl.AddAccessRule(rule);
      file.SetAccessControl(acl);
    }
  }
}

There are actually three problems with this one.

First, the whole concept you were trying to illustrate is now lost in details. People have stopped looking at the conceptual/high-level thing you were providing an example of and now they’re focused on your error checking and code format. Along with this, these examples are usually sort of long, so you run into the prose example problem again

Second, and related to that first issue, these examples totally open the door tonitpickers (a la Raymond Chen). “Your string formatting wasn’t culture sensitive and you didn’t localize the exception message!”

Finally, you get peoplecopy/pasting the code as though it’s production-ready without bothering to see if it does everything they need it to do, sometimes without even testing the code.

HOW DO YOU ESCAPE THE TRAPS?

The root of the problem is that people learn in different ways. Some people need that prose example or the Foobar example so they can focus on the concept rather than the details; others need more precise examples so they can see how things actually work in a more “real-world” environment.

There is a two-part solution to this, and it requires cooperation on everyone’s part.

For the people providing examples: Provide multiple examples of the same concept but using different styles. Describe in prose what you’re going to demonstrate and then give a precise concrete example. Or give an imprecise concrete example and clarify it in prose with maybe another example in the Foobar format. The idea here is that between two or more examples, at least one will make sense to folks, or they’ll be able to put concepts from the different examples together to make a complete picture.

The drawback to having multiple examples is that it is longer, so you’ll want to put the shortest bits first to draw the attention in and convey the most info you can up front. This is similar to the pyramid structure used when people write news stories.

For the people reading examples: Don’t get stuck in the details. There is an unspoken contract between folks reading an example and folks presenting examples. When a person is trying to convey some information to you in a succinct fashion, they have to trim things down for time or readability. As the recipient of that information, you need to understand and agree to that. If you get stuck on naming or nitpicking, stop for a second and realize you’re missing the point. If the example is talking about file permissions and there’s a missing null check, don’t worry about it unless you think it actually fundamentally affects your understanding of the example. Feel free to ask questions, but before you do, ask yourself if the question is constructive or would help you understand better… or if you’re just trying to be right about something.

WHAT OTHER TRAPS ARE THERE?

Did I miss an example trap? Ideas on how to provide better examples? Leave a comment!

net, web, vs comments edit

When you install IIS Express it also installs a self-signed certificate that it will use for SSL. This is not normally a problem, however, if you already have a self-signed certificate, it may result in a confusing issue where you have two certificates with the same distinguished name, like so:

Duplicate certificates with
CN=localhost

And why would that be a problem? Say you are working with WCF services that need to identify themselves with certificates. You have your dev machine set up to use the self-signed certificate, like so:

<serviceCredentials>
  <serviceCertificate
    x509FindType="FindBySubjectDistinguishedName"
    findValue="CN=localhost"
    storeLocation="LocalMachine"
    storeName="My" />
</serviceCredentials>

Now when you go visit your service, the channel is always faulted. Why? If you turn up the WCF end-to-end logging, you’ll see the following exception:

System.ServiceModel.ServiceActivationException: The service ‘/YourServiceHere.svc’ cannot be activated due to an exception during compilation. The exception message is: Found multiple X.509 certificates using the following search criteria: StoreName ‘My’, StoreLocation ‘LocalMachine’, FindType ‘FindBySubjectDistinguishedName’, FindValue ‘CN=localhost’. Provide a more specific find value.

Basically - Ambiguous match. Be more precise.

There is an article explaining how to use a custom SSL certificate with IIS Express that involves removing the SSL endpoint and re-creating it with the appropriate cert. Your other option, and the one I’m going with, is to identify the certificate for WCF by certificate thumbprint rather than distinguished name.

<serviceCredentials>
  <serviceCertificate
    x509FindType="FindByThumbprint"
    findValue="1234567890123456789012345678901234567890"
    storeLocation="LocalMachine"
    storeName="My" />
</serviceCredentials>

Far less human readable, to be sure, but more precise and totally unambiguous. Of course, if you’re on a development team, it means everyone needs to have the same dev certificates installed. Tradeoffs, tradeoffs.

This one took me a while to figure out and caused “Hulk Smash!” style rage during the search. Hopefully I can save you the same.

I was recently sent for a week to Sydney, Australia on business for a week. Having only been out of the US twice before (once to Aruba, and once to Canada, which doesn’t really count), I wasn’t really sure what to expect. Plus, it being a business trip, I didn’t expect to have much time for tourism. Luckily, we got a little more time than I expected to enjoy the area.

Travis standing in front of the Sydney Opera
House.

When I left home, it was snowing and icy, enough that I had to take the train to the airport rather than getting dropped off. It’s the end of Summer in Australia, though, so I checked my coat with my luggage and made the flight to LA, where, after a six-hour layover, I got on the 15-hour V Australia flight to Sydney.

The flight actually sounds worse than it is. V Australia has little individual screens in the back of each seat and a library of movies, TV, music, and games to entertain you. It wasn’t a short flight, but I had enough to keep me busy between that and my Kindle that the time went by faster than expected.

I and my coworker, Derek, left on Thursday, February 24, at 11:40a and we got into Australia on Saturday, February 26, at 6:15a. You lose a lot of time on the flight, plus you cross the international date line, so you lose a day there.

We took a taxi from the airport to our hotel, the Sydney Harbour Marriott at Circular Quay. We were lucky in that they already had our rooms ready, so we were able to check in and take a rest before heading out and taking advantage of our weekend for tourism. My room had a view of the Sydney Opera House, which made it very nice to wake up and peek outside in the morning.

View of the Sydney Opera House from my hotel
room.

After dropping off our stuff, we headed over to the Sydney Opera House and took a tour of the inside, learning about the architect, Jørn Utzon, and the way in which it was constructed. It was a very interesting tour and you get to see a lot of stuff that you don’t normally see since most of the time the views are of the outside, not the inside.

Looking out from the inside of the Sydney Opera House. You can see
the concrete ribs that form the
roof.

I think the thing that I found most interesting was the set of tiles on the outside of the Opera House. When you see it on TV, the Opera House looks totally white, but the tiles are actually a mix of white and cream color, so when you’re up close, there’s a different pattern to it. There are 1,056,006 ceramic tiles in a sort of chevron pattern. They’re self-cleaning, with the rain doing all the work. They’ve never had to replace a tile since construction completed in 1973. And there are no gutters on the building - the rain washes into the spaces between the tiles, runs down the outside, and back into the harbor.

Close up on the Sydney Opera House
tiles.Looking
up the roof of the Sydney Opera
House.

The rest of Saturday was spent sort of milling about the city, just getting a feel for things. We had lunch at the King Street Brewhouse, walked past the botanical gardens, but generally didn’t have a destination. The heat and humidity took some getting used to, with the air thick like molasses and having hopped pretty much straight out of snow and ice into summertime.

Sunday morning I got up early and made it over to Sydney Wildlife World as it opened at 9:00a. It was a little cloudy and rainy, so the heat and humidity was accentuated quite a bit. Wildlife World was actually really cool and you get to see everything from butterflies (in an enclosure, flying all around you) to wombats and cassowaries. I got there as the koalas were being fed, so while normally they are asleep from 18-22 hours a day, I got to watch a couple grabbing eucalyptus branches and eating breakfast. I also got to pet one of the koalas (named Sid) and get my picture with him. Finally, after the rain started settling down, they put some food out for the kangaroos and they hopped out to eat… and they let us pet the kangaroos, too. The kangaroo I petted was named Merv. (I didn’t get my picture with Merv since there was quite a line to come up and pet him, but I did get a picture of Merv.) The keeper in the exhibit mentioned that Merv has a pretty playful attitude and has been known to hop over the knee-high fence in the enclosure and wander around where the guests are.

Me and Sid the koala at Sydney Wildlife
World.Merv
the
kangaroo.

After Sydney Wildlife World, I headed up to The Rocks area in Sydney to do the Sydney Harbour Bridge Climb. It’s not a cheap endeavor, but it’s definitely worth the time and money. Derek went as well, and we had a group of five climbers (counting us and the tour guide, Simon). We went all the way up the bridge on the inside arch, climbed to the very top, and then came down the opposite inside arch. We got to see quite a bit about the inner workings of the bridge and the views of Sydney were brilliant. It’s reasonably exhausting, though, taking 1400 steps and burning roughly 500 calories (per Simon).

Travis on the Sydney Harbour bridge
climb.

We had lunch after the bridge climb at the Lord Nelson Brewery. I had a fairly tasty porter called “Nelson’s Blood” and a pizza with shrimp on it.

We wandered around for a bit more, but after the bridge climb, we were pretty much toasted, so we took a break until dinner. We thought we’d try the bar at Luna Park, since it’s supposed to have a nice view of the harbor, but they don’t really have a menu as such, so after having taken the train there, we caught the ferry back and had dinner at the Opera House Bar.

The entrance to Luna
Park.

Monday was our first day at work, but after work we headed over to Manly Beach on the ferry and had dinner at a local place, the Steyne hotel. At least, I think it was that; I am sort of blanking on the name of the place and Google Maps street view is telling me Steyne, so… there you go.

Tuesday after work we headed out with another coworker, Mike, and we had dinner at The Local Taphouse. They have a ton of local beers and you can get a “tasting paddle” where you get a small amount of five different ones to try. I had that and probably one of the best burgers I’ve ever had in my life. Very good, highly recommended.

Wednesday after work dinner was at Redoak Boutique Beer Café where I had some pretty tasty bangers and mash. We did a little more trinket shopping, but generally speaking, we took it pretty easy.

Thursday was our last full day at work. After work we went out with our co-worker, Tim, who makes the trip regularly. He showed us a nice place called the Belgian Beer Café for dinner, where I tried kangaroo. Tastes a lot like beef.

The Sydney Opera House at
night.

Friday being our last day (well, half day, since it was primarily travel), I got up early, had breakfast, and made one last trip around the Circular Quay area and the Sydney Opera House again. Then… train to the airport and the long flight(s) home.

Self portrait in front of the Sydney Opera
House.

My “I never travel” uneducated impression: Sydney really reminds me of a combination of Portland, Seattle, and Victoria BC. I felt very much at home walking around, the city looked like walking around downtown Seattle, and some of the historic buildings felt a lot like Victoria BC. It was a laid back atmosphere, nice and easy going. Oh, and there’s a nice bridge (like Portland!) and an Opera House (well, not like Portland). I had a great time checking things out and saw a lot of things I’d never seen while still being in a comfortable, familiar environment. I will definitely have to go back someday on vacation and spend more time not only seeing things around Sydney but also venturing out to other locations around Australia.

I posted a bunch of pictures of the stuff I saw over in Picasa (but only a fraction of the 550+ photos I took). Go check that out if you’d like to see more.

Travis, Derek, and a couple of locals on the Sydney Harbour bridge climb.
From 2011 Sydney Australia

General Ramblings comments edit

From a conversation at today’s staff meeting…

Dev 1: I’ve been catching up on all the old James Bond movies recently. We just watched Dr. No last night.

Me: Oh, that’s a good one. Hey, which is your favorite Bond? Actor, not movie.

Dev 1: Well, let’s see, there’s Sean Connery, George Lazenby, Roger Moore, Timothy Dalton, Pierce Brosnan, Daniel Cra-

Dev 2: Chuck Norris.

Me: What?

Dev 2: Chuck Norris. I saw this web site that says he can do anything.

So, folks, there you have it: Chuck Norris is the best James Bond.