Building A Better Sample Application

  • Article

Lately I've been working with the product teams on building new things that will be revealed at PDC 2008 (you are going aren't you?)  such as WCF and WF in .NET 4.0 and "Dublin".  I'll have many more details on this to come but today I want to think about sample applications.  If you are like me you probably look to samples to find all kinds of useful nuggets about how to do something.  I have some ideas on how to make a great sample but I'd like to know what you think.

Here is my list

Make It Focused

The sample ought to focus on a few things, not everything.  I don't have all day to study the code.  I want to pick up a specific technique or method for doing something.  I understand if you don't supply enterprise class error handling, security or monitoring to the code.  It's a sample after all - I'll pick those things up somewhere else. 

Make It Work

When I open the project and hit F5 it should do something cool.  Don't make me do 5 things before it will do something cool.  Don't have it just sit there not doing anything either and don't make me read a doc to figure out what to do.  Most of the time if there is a readme.txt I don't read it.  It's not that I don't want to it's just that I'm busy and I'm trying to get right to the point.

Make It Easy To Understand What Matters

Some samples contain a lot of code.  Much of it is boilerplate generated code or scaffolding code that really doesn't matter much for the purposes of this sample.  Here is a test.  In 5 minutes or less I should be able to open the solution, run the app and answer the following questions.

  1. What is the main point of this sample?
  2. Where is the code that demonstrates it?
  3. How does it work?
  4. Why should I care?

Why This Matters

Product teams spend months (and sometimes years) working on a feature to fine tune its implementation.  This is great, I'm glad they do it.  However you also have to consider closing the gap between a great implementation and the odds of an average developer being able to understand how to and why they should use it.   After spending so much time with your feature set these questions  seems obvious to the team that built them but you and I know differently.

What do you think?  What makes a great sample? 

Have you seen a great one?  What is it?  Why was it great?

I'm putting together my list and I really want to add your feedback to it so sound off and let's get some great samples.