keithbrown42

Tidbits from the Pluralsight trenches

I’ve been blogging over at pluralsight.com

leave a comment »

Seems like I’ve been saying all I need to say technically (which is mainly what this blog was for) over at blog.pluralsight.com. So I probably won’t be posting much here anymore. Follow me there!

Written by Keith Sparkjoy

March 10, 2012 at 6:22 pm

Posted in Uncategorized

I wish Twitter would provide a standard way to express times.

leave a comment »

I see this sort of thing all the time on Twitter: 4 hours until Foo happens!!!

Eight hours later, people are still retweeting it.

Using absolute times isn’t any easier due to time zone differences. It’s a *lot* easier to provide relative times like, “3 hours until…”, until you see how retweets completely destroy your intent.

I wonder if Twitter is thinking about ways of making this better? Imagine a world where I could use a standard syntax to establish an absolute point in time, say “T+3h” for, “the point in time 3 hours from now”, or T9:00 for 9:00 local time (which my twitter client would convert to universal time before sending to Twitter), or T16:00U to express universal time directly. I’m sure there’s better syntax, but you get the idea.

Twitter would then always render these in a standard way using universal time, and clients could do simple things like make it clear that the time is in the future or in the past (reducing accidental retweets of stale event announcements, etc.) You could hover your mouse over one of these dates and your client could pop up a tooltip showing it in relative time, like “in 6 hours”, or you could configure a preference to always compute and display relative times when they are within a certain number of hours of Now.

I’d love to know if anyone at Twitter is working on solving this problem, but I’ve yet to come up with a good search expression for this topic. “Twitter time” gets you a bunch of posts on how to avoid wasting time with twitter. “Twitter dates” gets you lots of posts on how to get a date using Twitter. “Twitter express standard time” gets you posts about express rail and air service times.

Sigh.

Written by Keith Sparkjoy

December 1, 2011 at 7:09 am

Posted in Uncategorized

Keith and Mari ride to Yellowstone

with 2 comments

Saturday, Oct 8 we headed out from Syracuse UT, riding up I-15 to Brigham City, then through Logan via highway 89, up through Logan Canyon, by Bear Lake, through Idaho and into Wyoming, where we spent the night in Jackson.

It was cold. It snowed on us. We skirted some ice patches on the road over a couple of mountain passes. But we dressed warm, cranked up the seat and grip heaters on the Vision, and hunkered down. And boy was it worth it. We saw some of the most beautiful fall colors. We didn’t see a single motorcycle on the road, which meant I could relax and not worry about waving at everyone :-) We did see one motorcycle in Yellowstone park, but I think it was a park ranger. We got lots of attention as we walked around Jackson with our helmets – lots of folks were admiring the bike. I had more than one guy tell me how bad ass we were to make the ride at this time of year.

The following day we rode through Grand Teton National Park on our way into Yellowstone.

We made it!

There were lots of low clouds so our view of the mountains was limited to the foothills on the way in. But the fall foliage was on fire!

There was a little bit of ice on the road here and there, and I was really careful going over bridges as we rode over mountain passes in Yellowstone. By the time we got to Old Faithful, the day had started warming up quite a bit.

When it hit 50F we were pretty happy :-) It was pretty chilly riding back to Jackson that evening, but we got in before dark and warmed up in the hot tub at the Elk Country Inn before going out for a delicious dinner at Thai Me Up (if you’re hungry for some Thai in Jackson, be sure to visit them – their home brewed beers are delicious).

The next day was partly cloudy and still a bit chilly as we headed back home. We added some hand and feet warmers to our attire and Mari picked up a neck gator. We stopped in Alpine, WY for a late breakfast at Yankee Doodle’s – Stephen Colbert would love this joint. Delicious food, and an incredible attention to detail as everything in the restaurant was red white and blue.

As we rode South, the day continued to warm until we were riding through Idaho at a comfortable 54F. By the time we got back into our hometown of Syracuse, UT, the temp was up to 64F and there were several motorcycles out and about.

It was quite an adventure. I was ready to turn around at the first sign of trouble, but we stuck it out and it was well worth it!

Written by Keith Sparkjoy

October 10, 2011 at 4:45 pm

Posted in Uncategorized

IEnumerable considered ambiguous

with 6 comments

It’s tempting to use IEnumerable<T> liberally in public APIs as a “least common denominator” interface that can represent any collection of objects.

Consider two very different things that could be lurking behind an IEnumerable<T>:

A: An in-memory collection such as an array or list.

B: A lazily evaluated fire hose that hides complex network logic that makes batch requests and yields objects from those batches.

For (A) it’s safe to enumerate the collection multiple times, use the Count() extension, transform with ToList/ToArray, etc. while it could be disastrous to do the same with (B).

How are you supposed to know what you’re getting when someone hands you an IEnumerable<T>? In the vast majority of cases, you’ve probably got (A). Indeed, most programmers will assume this and program against it as an in-memory collection, and they’ll run into trouble (perf problems or worse) when they encounter (B).

Consider a method that takes an IEnumerable<T> as an input. Is it safe to pass a (B) to that method? It’s impossible to know without looking at the implementation.

You could take an IList<T> or an ICollection<T> instead, but these interfaces have mutators on them, which introduces additional ambiguity – does your method modify the collection being passed in?

I’m curious to know what conventions others are using to deal with this ambiguity.

Written by Keith Sparkjoy

August 3, 2011 at 6:36 am

Posted in Modeling

Immutable objects in C#

leave a comment »

Recently I posted about how I use C# named parameters to clarify my intent when I call a method that takes arguments of the same type. Well, here’s an even better use for them: designing immutable objects.

Sure you can hide an object’s state behind public methods and property getters, but if you really want to encourage immutable objects, you should consider implementing the class’s internal state via readonly fields. Indeed it becomes as simple as this:

public class Cooldown {
  public readonly string Ability;
  public readonly DateTime ExpiresOn;
  // ... several more fields

  public Cooldown(string ability, DateTime expiresOn, ...)
  {
    Ability = ability;
    ExpiresOn = expiresOn;
    // etc.
  }
}

Prior to .NET 4.0 this wasn’t very easy to do. And that’s because objects in C# with readonly fields require that those fields be initialized by a constructor, and a constructor can get pretty big if all of the fields are readonly. But this awkwardness goes away with .NET 4.0. Now I can construct a readonly object and not loose any clarity around what data is going where:

new Cooldown(
  ability: "Invisibility",
  expiresOn: DateTime.UtcNow.AddSeconds(30),
  ...);

In his book, Domain Driven Design (DDD), Eric Evans encourages the use of Value Objects in domain models. Here at Pluralsight we are using the DDD approach to modeling, and we are taking his advice and using immutable objects to implement all of our Value Objects in the domain. What we’re finding is that we are programming in C# but our code is becoming more and more functional in nature, which feels like a good thing. Less mutable state tends to make things easier to test, and tends to reduce bugs.

The one gotcha to all of this is that until mainstream serializers and O/R mappers know how to use constructors to initialize Value Objects, we won’t be able to use them directly to persist our entities. Here at Pluralsight we think the sanctity of our domain layer deserves a corresponding set of serializer-friendly data transfer objects, and we’re taking the time to completely isolate our domain from our persistence logic. Not everyone is willing to go to that extreme, in which case they won’t be able to benefit from this today in their domain model. I’m hopeful in the future we’ll have serializers and O/R mappers that recognize the importance of readonly fields and add support for constructor-based deserialization.

Written by Keith Sparkjoy

July 1, 2011 at 5:24 am

Posted in Uncategorized

Taking executable specs to the next level: Executable Documentation

with 4 comments

Here at Pluralsight, we’ve been using Machine.Specifications (mspec) for a little over a year now to implement our unit tests. Given how quickly formal documentation goes out of sync with code, many people smarter than me have advocated that unit tests can be used as documentation for a class. And this might work, if

a) The question you have is very specific (e.g. you can do a FindUsages on a method/property and quickly see the tests that exercise it), and

b) A test exists that exercises the method/property you’re trying to understand.

This morning I had a look at the specs for one of our aggregate roots that resulted from its TDD to see if it was adequately documenting its public API, lifecycle semantics, etc. What I saw was a jumbled mess of specs that weren’t designed at all to focus on what a user of that class cares about. Don’t get me wrong – the specs we had in place were all very helpful, but they were focused on testing little bits of functionality, much of which was internal to the package. And even if I could filter out the internal stuff and just leave the specs covering the public APIs, there was no order to any of it. I couldn’t look at my specs and figure out how the class should be used, from its creation through its various states, until it’s archival. Its lifecycle wasn’t clear.

Plus, the language of the spec wasn’t focused on being readable for an end user. When I look at a typical specification that I wrote during TDD, I saw something like this:

When making an invoice

  • Should have a date of Now
  • Should have the customers name
  • Should have no items

This is perfectly fine as a unit test, but isn’t quite what I want for documentation. Here’s language that I think would be more helpful as documentation. Note how I use the actual names from the public API:

When you invoke MakeInvoice on an InvoiceFactory the new Invoice

  • Has todays date
  • Has the customers name
  • Does not have any items

Heck, I can write specs like that. So I figured I’d give it a try this morning. The exercise was very enlightening.

Leaving all of my existing unit testing specs in place, I added a new folder, InvoiceDocs, and I wrote additional specs to act as “executable documentation” for the Invoice class. Here’s what I did in InvoiceDocs:

  • I added specs covering the entire public API of the Invoice class, omitting anything that wasn’t useful to a client of the class
  • I *ordered* the specs so they showed the lifecycle of the Invoice class, from creation to archival, documenting the exact API names for a newcomer
  • I used language that would be approachable for a newcomer

And in the process, I learned some things. I now know how to create executable documentation for my public API as I develop the class using TDD. Next time I will write specs for my public API in a separate *Docs folder using these conventions as I TDD. As I wrote my documentation specs, I found some things that were awkward to document. This led me to refactor my domain model to make it easier to document, which naturally made it easier to use. I found the executable documentation driving me to refactor toward deeper insight. Very cool – as if we don’t have enough ways to “drive” design, now we have “documentation driven design” ;-)

When all was said and done, I ended up with executable documentation that will fail the build if it’s not correct. Kind of. There’s still one flaw that we should think about fixing together. In MSpec the “When” statement is driven by a class name. Embedding API names in the class name isn’t something that will lend itself well to refactoring, and this will get out of date unless I am vigilant. So the solution is far from perfect. It’d be very cool if we could have the option of putting the When statement into an expression of some sort so that the names of APIs would be part of an expression that can be refactored. One step at a time, I guess.

It took me a few iterations to figure out how to get my specs to show up in a nice, ordered fashion in the test runner. After a few initial attempts at adding numbers to the class/file names, I realized I could simply use the Subject attribute of each specification to order my tests appropriately. The namespace was already stating the subject, so this didn’t seem to hurt anything, but I’d like to start a conversation around better ways of ordering tests/specs in runners so that we can start accomplishing this more naturally. Here’s what one of these “ordered” specs look like:

    [Subject("01")]
    public class When_you_invoke_MakeInvoice_on_an_InvoiceFactory_the_new_Invoice
    {
        // ...
    }

Written by Keith Sparkjoy

June 26, 2011 at 8:54 am

Posted in Modeling

Use C# named parameters

with 2 comments

As of .NET version 4.0, C# supports named and optional arguments. This comes in really handy for distinguishing method parameters that have the same type. For example:

public interface IGenerator<T>
{
    T Generate(T min, T max);
}

It would be really easy to accidentally pass arguments to Generate in the wrong order, since they have the same type. But using named arguments, you can be a little bit more explicit, which helps reduce the chance you’ll screw up:

var n = generator.Generate(min: 0, max: 42);

I try to follow the rule that no method should take more than two arguments, so I end up using this technique most often with constructors, which often need to take a lot of parameters. But more on that in another post…

Written by Keith Sparkjoy

June 22, 2011 at 6:03 am

Posted in Uncategorized

Follow

Get every new post delivered to your Inbox.

Join 213 other followers