Building A Better Sample Application


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.


Comments (5)

  1. Ashi says:

    When the users download the Sample application it should have the article link or the article documentation in it.

    What are the typical usage scenario of the feature should be noted in the conclusion.

    Also the sample application should include reference links to community articles out there.

  2. Ashi says:

    When the users download the Sample application it should have the article link or the article documentation in it.

    What are the typical usage scenario of the feature should be noted in the conclusion.

    Also the sample application should include reference links to community articles out there.

    Ashith Raj

  3. J Healy says:

    All that sounds good, and I’m guessing you folks will do a great job on samples. But there is among the existing sample apps one that needs a Dublin port – .NET StockTrader.

    StockTrader isn’t of the 5 minute variety, but porting it off of Configuration Service 2.0 onto .NET 4.0, Oslo, and Dublin would be an outstanding pre- / post- example of what the technologies bring to the table.

  4. Naim Ru (naim.ru~AT~gmail...) says:

    Your main points are right on target. However, I do not agree with the following:

    "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."

    This is a tough one, and somewhat understandable from the sample-author’s POV, but I think is ultimately a disservice to the community.

    This may be fine for code snippets that demonstrate a very small aspect of an API, or a single specific technique. However, by having most of your working samples not demonstrating "enterprise class" quality, I am afraid that you are reinforcing bad practices for many many junior and mid-level developers out there.

    Kind regards,

    Naim Ru

Skip to main content