Dan Swearingen’s Tech Stuff Blog

Have you ever had a disagreement about when something is actually done (as opposed to “not done yet”)?

I started learning about “done” when my parents started making me do chores around the house.

Doing dishes: Walk to sink, wash dishes, put in drainer. Done. Am I right? I though I was right.

“Did you empty out the dishpan?” my mom asked.

“No.”

“Well, you’re not done yet.”

Later, I say “now I’m done.”

“Did you wipe down the sink, counters, and stove?”

“That’s part of ‘washing the dishes?’” Even a ten year-old understands the concept of scope creep. The answer was yes but through my push-back I won a change in the name of the task. From then on “Doing the dishes” had to be called “Doing the dishes and cleaning up the kitchen.”

The bottom line: in a team environment the implementer can influence but does not own the determination of when a task is done. Like project scope, doneness is a value negotiated with the customer of the work.

I was recently asked to define “done” in my organization. This is a clear sign that something might be broken. Maybe it just means that there have been recent disagreements about done?

What is Not Done?

I often find that a helpful way to define a positive value is by defining the corresponding negative value.

Not Done is also “it doesn’t work.” To me this is an obvious corollary but I find that this does not occur to some people. The reverse is certainly true.

Not Done is when code “Works on My Machine.” I cringe when I hear “it’s working on my machine” especially since this is typically a response to someone saying “I can’t get it to work” This is ESPECIALLY bad when heard in response to “I can’t get it to build.” When a developer says “it works on my machine” they are really saying:

I do not know what this software depends on.

I do not know what’s involved in moving this software to a clean machine.

I have not checked in all the required code into the source code control system (and I probably don’t know what’s missing).

I do not really care that it does not work on your machine. I’m hoping that’s your problem…

Not Done is when code has not been tested. Untested code does not really work. This is because code that has not been tested invariably has some issues when actually exercised. I consider unit testing the absolute bare minimum level of testing before code can be considered done. An alternative to unit testing? Sure, a full blown test team.

Not done is when code cannot be reliably deployed. This is related to the “it works on my machine” issue. Reliable deployment means the developer has thought about all the steps, interactions and dependencies their code has and has documented them in detail sufficient to allow installation. Maybe the developer even went wild and wrote some install scripts or set up a full featured installer. It could happen.

Documentation

Is documentation required before code can be considered Done? If the code cannot be replicated, tested, or deployed without some written assistance then yes, it cannot be considered done until enough documentation has been written.

I find explaining to a developer that this piece of code is theirs to work on forever and ever until they write enough documentation to hand it off works as a powerful motivator to getting documentation written.

So What does Done mean?

Based on the discussion above I think I’ve outlined my definition of Done:

It has been tested.
It is reproducible and deployable on all supported environments.
It is documented sufficiently.
Most importantly (recalling my experience with the dishes), the customer agrees that it does what they want.

This post is based on a short demo/talk I gave at Vertigo recently.

I have two main goals in this discussion:

• How VS2005 handles WPF projects/apps (showing some Blend / VS2005 gotchas)
• A way to look at the role of XAML in WPF architecture

Petzold books

Charles Petzold’s books have always been a huge help to me in getting all the nitty gritty details in Windows UI technology. I started my Chuck P. habit way back with his Programming Windows book. The Book for Win32 Windows programming. Ok, I do have other books too but this is the one I’d want if I was lost on a desert island alone with a c-compiler…

More recently, Petzold has written authoritative .NET WinForms books and I started to notice a trend. Especially in Programming Microsoft Windows Forms, his .NET 2.0 WinForms book, Petzold really pushes a code-everything-yourself approach as opposed to using any of Visual Studio’s “helpful” tools. His point: if you do not understand the code the various visual designer/code generators in VS create, you really do not know what is going on.

I see this as just another statement of the well-known Weasley’s Law:

Never trust anything that can think for itself

if you can’t see where it keeps its brain!

Arthur Weasley — Harry Potter and The Chamber of Secrets

I’m going to focus this very small discussion on how XAML fits in to the WPF dev process and WPF architecture and point out a few gotchas in the current WPF dev tool set.

The WPF dev process

I’m going to step through building a baby application modeled closely on the sample application Microsoft provides at MSDN in Get Started Using Windows Presentation Foundation but I’m going to walk through it highlighting aspects Petzold points out in his new WPF book Applications = Code + Markup.

Prerequisites

If you want to build and execute the demo code you will need a working WPF dev environment which requires the following: the Microsoft .NET Framework version 3.0 and the Windows Software Development Kit (SDK), Visual Studio 2005 (C# Express ok), Visual Studio 2005 extensions for .NET Framework 3.0 (WCF & WPF, November 2006 CTP or newer), and Microsoft Expression Blend (RC Version or greater).

First let’s play with a trivially simple WPF project. Source code here.

Step 1

We start Start with an empty WPF project in VS2005 which I’ve named WPFDemo.

In Solution Explorer, click the Show All Files button.

Select the files: (all the code files in the Step 1 folder)

App.xaml

ExpenseReportPage.xaml

ExpenseReportPage.xaml.cs

HomePage.xaml

HomePage.xaml.cs

Right-click on them and Include In Project.

Look at App.xaml:

    1 <Application

    2   xmlns=“http://schemas.microsoft.com/winfx/2006/xaml/presentation“

    3   StartupUri=“HomePage.xaml“>

    4 </Application>

App.xaml declares the application starting point. So let’s try to build. Assuming you followed the steps exactly you will see the following build error:

WPFDemo.exe does not contain a static ‘Main’ method suitable for an entry point

This is because by default when App.xaml was included by Visual Studio its Build Action was set to Page.

Select App.xaml and change its Build Action to Application Definition. Confirm that the application now builds and runs correctly.

Note: App.xaml is the most common name for this file but there’s nothing special about the name App.xaml. What’s important is its content and that it is configured as the Application Definition. Since the error message we got above implies this configuration has something to do with the Main() method it should also make sense that an application can only have one file configured as the application Definition.

In the steps above I’ve enacted discussion that may be found on pp. 479-481 of Petzold’s Applications = Code + Markup.

Where’s Main()?

After a quick examination of all the files we included in the project so far you should be asking about Main() – like, where is it? App.xaml defines the entry point to the application and if you dig into the generated files for the application you will find an App.g.cs file in the obj\Debug folder:

Examining this file we find a Main():

   33     /// <summary>

   34     /// GeneratedApplication

   35     /// </summary>

   36     public partial class GeneratedApplication : System.Windows.Application {

   37 

   38         /// <summary>

   39         /// InitializeComponent

   40         /// </summary>

   41         [System.Diagnostics.DebuggerNonUserCodeAttribute()]

   42         public void InitializeComponent() {

   43 

   44             #line 3 “..\..\App.xaml”

   45             this.StartupUri = new System.Uri(“HomePage.xaml”, System.UriKind.Relative);

   46 

   47             #line default

   48             #line hidden

   49         }

   50 

   51         /// <summary>

   52         /// Application Entry Point.

   53         /// </summary>

   54         [System.STAThreadAttribute()]

   55         [System.Diagnostics.DebuggerNonUserCodeAttribute()]

   56         public static void Main() {

   57             XamlGeneratedNamespace.GeneratedApplication app = new XamlGeneratedNamespace.GeneratedApplication();

   58             app.InitializeComponent();

   59             app.Run();

   60         }

   61     }

The #line 3 directive causes any compile error occurring here to be directed to the file indicated: back to the XAML file. The #line default, #line hidden directives restore error indication back to normal. These directives also affect debug step-through.

The key takeaways from this example are:

• VS2005 creates all kinds of generated files you should be aware of.
• Even a “pure XAML” app involves additional generated code and files.
• VS2005 patched for WTF is not (yet) fully XAML aware.

Obviously it would be great if we could wait for the next release of Visual Studio codenamed “Orcas” (Here’s a great site by Scott Guthrie all about Orcas). But here at Vertigo we’re delivering WTF applications today so we need to be aware of the issues – and build anyway.

I’ll jump ahead by simply pasting in more UI content to the application and demonstrate a typical but very simple Blend/VS2005 development scenario. Source code here.

Step 2

Without making any changes to the structure of the app but adding UI code we get:

The idea is that you select a name on the list and click the button to view that person’s expense report. If you’re curious: the data displayed is hard coded as XML structured data in the HomePage.xaml file.

The first thing to do is to name the Button element in the HomePage.xaml file. To me it’s interesting that we already built and ran this app and yet nothing squawked about the button being an un-named element.

Being a Visual Studio-centric kind of guy I naively click on the button in the Design view and look at the control properties.

First I look for the “Name” property. Huh, not there.

Ok, next I look for the “ID” property. Double-Huh, that’s not there either?

To name the button you need to go to the XAML code and in the tag <Button add Name=“btnView“. Note that there is Intellisense support within the XAML code an the Button tag.

Now I want to wire the Click event.

Can I access control events in the Properties panel? No.

Can I double-click on the button in the design view to add a click handler? No.

However, I can add a reference to the “Click” property in the Button tag but this does not automagically wire up an event handler stub.

What I can do is this: rebuild the app (not just Build but Rebuild) so that the Name I gave the button is in-scope for Intellisense and then add the handler in the XAML file’s associated .cs file.

In HomePage.xaml.cs, I add the event handler by starting to type “btn…” whereupon Intellisense shows me the btnView and I add the event handler and let VS2005 create an event handler stub.

All looks ok – and utterly familiar. I then edit the handler to call goToExpenseReportPage() which I have already prepared and the application is finished.

Now let’s add a twist. Go to the event handler and select the btnView_Click name and select Refactor / Rename and rename the event handler any other random name. I used ShowExpenseReport. Rebuild the code and confirm the application still works correctly.

Mixing it up with Blend

Now open the same solution in Blend.

Select the button in the design view and select the events list in the properties panel.

Note: from Blend’s perspective the button’s click event is not wired up. This is because Blend manipulates the application by only looking at a project’s XAML files, not its .cs files. Therefore, it is excruciatingly easy at this point to go ahead and wire the click event up AGAIN.

Just to make a point, let’s do just that. let’s wire up a second event handler to the button.

In Blend double-clicking in the click event box shown above wires up the event and creates the event handler stub in HomePage.xaml.cs. This sequence should open and/or foreground VS2005 to the created stub. We can add a call to goToExpenseReportPage() and the code builds fine but may, or may not, run fine. On some machines the second event handler fails when called because navigation has already moved to the second page, disposing of objects needed by the handler code so you get null reference errors.

If we examine HomePage.xaml.cs we note that it still only shows the first event handler wired that we created with VS and does not show the connection to the second Blend created handler.

If we examine the XAML file we find the button tag has a reference to the Blend created handler (Click=“btnView_Click“/>) but no reference to the VS created handler. T add more confusion, the VS takes the Blend created event handler reference and generates the expected hookup in the generated file obj\Debug\HomePage.g.cs:

#line 81 “..\..\HomePage.xaml”

this.btnView.Click += new System.Windows.RoutedEventHandler(this.btnView_Click);

Again the #line directive redirects debug and error output.

Given that we’re building our apps with a combination of Visual Studio and Blend what should we do?

Blend/VS2005 recommendations:

1. Use Blend to wire the events and create stubs. This means the event will be seen in the element’s tag in the XAML.
2. Use the default name for the event handler.

Number 1 implies that a typical WPF app will have events and handlers referenced to controls in the XAML file, the handlers in the code-behind file, and actual code wire-ups of the events in the generated .cs files (the code-behind-behind files).

If you look purely at the code behind file (XAML.cs above) you are going to see the handlers with nothing more than their names to hint which control they bear on.

This is why I say (Number 2) renaming event handlers away from the default [control name]_[event name] pattern is a bad idea.

Why emphasize and favor using Blend? Currently Blend behaves in design mode the way we wish Visual Studio would. I’m sure this will all have to be revisited once Orcas ships but for now this is the approach I recommend.

XAML in WPF

At the beginning I made some claims that I would discuss XAML’s role from a more architectural point of view.

In architecture docs at MSDN I found two statements that seem to bear on this:

If you work the first half of Petzold’s Applications = Code + Markup, that is, the non-XAML part, you find that making a WPF is properties, properties, properties. Set the 85 bagillion properties of a Window, of a button, etc.

But look at it this way: properties are data. Data can be easily described by XML. Enter XAML. Once you have all the properties in your applications held in XAML it becomes really easy for any number of tools to traverse and modify this data.

We just demonstrated this by using Blend and Visual Studio to act on the same XAML files. The process is not perfect yet but it is a powerful technique I think we will see more and more often.

“In addition to our summer and winter estate, he owned a valuable piece of land. True, it was a small piece, but he carried it with him wherever he went.”

From Woody Allen’s Love and Death.

So, what HAVE I been spending my time on? My little piece of the Windows Vista operating system.

For the last 20 months I’ve been building the digital locker assistant (DLA), a dedicated download client that works with Microsoft’s online digital locker, which is in turn part of Microsoft’s Windows Marketplace. Windows Marketplace is where that mysterious “Windows Catalog” link on your Start/Programs menu goes to.

Windows Marketplace supports direct browser based downloading. However, when the download is greater than 1-2 Gigabytes using the DLA is a much better way to go. The most popular use of the DLA so far has been buying and downloading entire copies of Windows Vista and Office 2007.

We were rather skeptical that users would want to download Vista or Office since they are really big downloads. However, earlier in the year the success selling and downloading super large games from Windows Marketplace convinced everyone that downloading Vista would be attractive to consumers. And indeed it has!

You can get the digital locker assistant two ways: If you have Windows XP, go to the Windows Marketplace website, create an account and download and install the MSI. It’s only a 1 meg download.

Or, it’s built into every copy of Windows Vista (except Server versions).

Actually building a part of Windows Vista was a huge effort but it’s really neat to install Vista and see my little piece in there. When I say “my,” it’s more like I’m using the Pluralis Majestatis, the Royal We. I was part of a team and We had LOTS of help.

I was the dev lead for the DLA for XP and Vista. Two very senior Windows developers with me at Vertigo, Chris Idzerda and Ralph Arvesen, rounded out the dev team (that is, they actually did most of the work). Initially, I was dev lead and PM but soon we needed more help with the process and got a full-time program manager, Anne Warren, who was also PM for the Windows Marketplace (WMP) website. The website dev team was some 15 developers and we had a build team of one (that should have been three). Our test team was in India so the dev/test cycle was almost 24/7, something like 24/6 – we’d hand off work in the afternoon and it would be tested all (our) night with a nice bug list waiting for us in the morning.

And then there’s the rest of the Vista team at Microsoft: really a cast of thousands. I think they ALL emailed me at least once. The High DPI functionality team. The Localization team (“do you know your UI looks really bad in Arabic?”), the Group Policy team, Remote Desktop team… you get the picture.

Let’s look at the app

In Vista there are two ways the digital locker assistant (DLA) may be invoked. The primary way is when you buy something at Windows Marketplace and it’s in your digital locker and you click “download.”

You may also browse to the DLA by finding it under the Vista Control Panel.

Then look under Programs or Programs and Features (using Classic view) and find “Manage programs you buy on line.” If you open this link you will invoke the DLA and if you have never sync’d up with your online digital locker you will see this:

If you have software in your online digital locker you can see it listed here by clicking on “Sign in if you already have a digital locker account.” Digital locker accounts are Windows LiveID (a.k.a. Passport) accounts mapped to a Windows Marketplace account. You’ll get a login prompt:

and after synchronizing with your online digital locker you’ll see all your purchased, free, and trial items listed. In my case (below) I clearly have a bunch of games in my locker. These were just to test downloading large items. Right.

Technology under the covers

The DLA is built in Win32/C++ as an ATL Windows application but we get some goodies from WTL as well. For those going “huh?” look at my post ATL and WTL resources.

At this point most people are asking me: why C++? Why not .NET and/or WPF? Or, if you’re using C++, why not MFC?

The DLA started (and is still available) as a downloadable application for XP. Our target users are what Alan Cooper would call “permanent beginners” (like that relative that always calls you for tech support…) — with a modem.

This means making the download as small as possible. Vertigo is a premier .NET shop but we could not use .NET because the 22 MB .NET runtime install kills us (that .NET never made it into the XP Service Packs… argh). Fortunately, we happen to have a few developers around (i.e., old geezers) who can do C++. We used ATL again to keep the size of the executable small.

In hindsight, it was just as well that the XP effort started in C++. Once we expanded the project to include being built into Vista we found that, in Windows System programming and the Vista source tree, C++ is expected and still king (See my post Has Microsoft flipped the Bozo bit on .NET? for a full discussion).

This meant that we could develop one source code base and, with some care, make it build in the Windows OS build system for Vista and VS2005 for XP.

Single source is nice but why not make a single binary that runs on Vista and XP? Sigh. We do — sort of, but it’s complicated.  From a programmer’s perspective, Vista makes one dramatic change from traditional Win32 applications and that’s in how localized resources are loaded.

To handle localization traditional Windows practice is to create an RC file for all resources (dialogs, images, sounds, strings, keyboard shortcuts, etc.) which are compiled into the resource DLL. Localization teams produce localized RC files based on your master RC file and these are all built into a suite of resource DLLs. At run time the application loads the appropriate resource DLL based on logic you have to write which looks at the calling thread’s locale settings.

Internal to the application is a language-neutral block of resources (typically English-US based) and if an appropriate external resource DLL cannot be found for the current locale settings, this internal block is used instead. This is known as “fallback” behavior.

Here’s the new twist in Vista: in Vista the OS loader (not the app) picks the resource DLL and locates it in memory where the app thinks its internal fallback resources are. This is expected behavior and currently only appears to work for a native Vista-built application so our “legacy” resource loading technique as used in XP was not acceptable to those who guard the Windows Source tree. Did I mention all the code reviews? Making Vista-style resource loading work in XP, while theoretically possible, was a task we did not choose to take on. So we ended up with one set of source code feeding two build processes; one for XP and one for Vista. Through careful coding there are remarkably few “if Vista do this, if XP do that” points in the code. 

While we currently block running the XP installer on Vista (in theory blocking installation of the XP DLA on Vista), it turns out that the XP DLA runs fine on Vista. I should not be suprised by this becuase we did quite a bit of casual sanity testing on this but it was not initially part of the test matrix. We found out by somewhat by accident as users were upgrading their XP machines (where the user had added the XP DLA) to Vista and then running the XP DLA.

For our downloading mechanism we hand off all download jobs to Microsoft BITS (Background Intelligent Transfer Service). While BITS works well for us I still think Micorsoft is tempting the gods by including “Intelligent” in their product name. BITS is the guts behind hwo Microsoft Updates are downloaded. I’ve also discovered that Google Updater uses BITS as well. What we gained by using BITS was automatic download management including background downloads, downloads that persist when our application is not running, downloads that seamlessly restart when the machine is rebooted, and lots of error handling algorthms that we did not have to write or maintain. I’d use BITS again if needed. We did have to build a simple HTTP download as well because some modem-based accelerators do not play nice with BITS.

Overall it was a great experience. While it was sometimes chaotic and exhausting, it was a lot of fun too. 

I’d do it again.

Really.

After I’ve had a couple years to rest.

Jeff Atwood (Coding Horror) graciously invited me to share in his recent Five Things You Didn’t Know About [Jeff Atwood] (and [his] office) post.

I too have been humbled and impressed by the other people’s stories in the Five Things meme so here are mine:

1.  I am baffled by other people’s fascination with professional sports.

I can identify with playing a sport – I just cannot understand the motivation behind the activity and entire economies driven by watching, talking, and writing about sports. That a city cares whether or not it has a football team and whether they have a nice stadium when at the same time its schools suck makes no sense to me. That a soccer fan needs to throw a beer bottle at someone who does not like their team makes no sense to me. 

2.  My family set me up to meet a girl they thought I’d like – and it worked.

I met my wife Janet at a family Thanksgiving dinner after months of my family telling me “oh, we want you to meet this girl we think you’ll like.” We’ve been together for twenty years since that day.

3.  I am an Astrophysicist by education.

My career in software is a profitable side-effect. In school I was interested in everything and focusing on one thing to get a degree in was a challenge. Science seemed to be a recurring interest and my employer at the time (Hewlett-Packard) would pay tuition in that area so I chose to major in physics. After my BS I changed schools to work on a Masters. I was at Cal. State Northridge and they had a world class solar observatory and the astronomers were nice to work with so my M.S. in Physics was based on research into the solar magnetic field structure’s relationship with gas brightness and velocity. For my Ph.D. I wanted to work on something other than solar astronomy so amongst the multitude of choices I had (I think it was two) I joined the astronomy department at Indiana University, Bloomington. I was there five and a half years and finished my coursework, my Physics and Astronomy Ph.D. qualifying exams, and made good progress on my dissertation research. However, family and financial issues prevented my staying the extra one or two years it would have needed to complete my Ph.D so I left IU with a “thank you for playing” Masters in Astronomy. In the mean time I had picked up good programming skills that people were very interested in paying me for.

4.  I am an artist by inclination.

My family is populated mainly by performing artists and musicians. Throughout my life I have built things with my hands and the design and construction of structures of fantasy remains my hobby. I’ve focused on model railroading but I also draw and build other 3D art forms. The artist in me determines whether I’m interested in a project: if there’s room for creativity I’m interested. If you just need me to turn the crank, I’d rather be digging ditches.

5.  I’m a recovering Aspie (link)

This might be something you already know. In which case my not realizing you know is a demonstration that I have Asperger’s Syndrome. That’s an Aspie joke.

I was not diagnosed until I was in my 30s. I had always known I had to work especially hard at things that appear easy to people around me and all my life I have been known as “really smart – but weird.” It has been really helpful to have a diagnosis. It hasn’t changed anything I do but it has helped me feel vastly better about the coping mechanisms I employ. I still have most of the traditional problems Asperger’s deal with. Let’s face it, most good software developers are what we call “on the spectrum” so I’ve always fit in really well in good development organizations. However, unenlightened employers almost invariably feel I’m stubborn and arrogant when I’m actually very shy and I strive very hard to be a nice person. As far as being stubborn, I like to think I mitigate it by usually being right (although I now know it usually doesn’t matter that you’re right, I’m still naïve enough to be surprised). Fortunately, I’ve had enough really good employment experiences over the years to be comfortable with what part is me and what part is them.

In my fourth grade class we had a two day workshop put on by representatives from NASA. The Space Race was big in American life at that point. The activity was a simulated mission to Mars with the class divided into mission control and crews of two ships traveling together. On the morning of the first day we were informed that one of the ships had crashed on the surface of Mars and was unable to make the return flight. I was in charge of life support on one of the ships. In a few minutes I provided a solution with charts and resource burn-down graphs. By doing that I effectively ruined the next day and a half of the activity for the whole class.

Soon, after days of tests and interviews I spent less and less time in my regular class and starting in 5th grade was moved to a special class with a only six students (2 each in 4th, 5th, and 6th grades) and told I could study whatever I wanted. I studied the history of transportation, astronomy, puppet theater, building geometric shapes out of manila folders, whatever my interests wandered to. As a class we regularly left school and took a bus downtown to get books out of the San Francisco main branch library as needed since we exhausted the resources of the school library after a couple weeks.

For the next four years I was in the San Francisco schools I never sat in a regular classroom and had the most fun I ever had in school (until graduate school). Every now and then someone would stop by with a textbook and say something like “Dan, you really need to learn some math. Work these chapters, please?” A few days later I’d hand in the work and could go back to following my interests.

When I was middle-school age I moved away from San Francisco. High school and college were much harder. Many teachers mistook my shyness (silence) and inability to flow with the program as stupidity. They would put me in remedial reading one week and only to return me to “A track” (college prep) the next after demonstrating reading over 1200 words per minute (as high as their machine could go). I graduated high school with a D-plus GPA but nearly maxed out my SATs. Only in graduate school and when working on a Ph.D. in astrophysics was I having fun in school again.

I’m a former United States Marine. That probably should make six things you didn’t know about me. I put it here in the Asperger’s portion because many of my most effective coping mechanisms were learned during training in the Corps and I’ll always be grateful for that. I also learned how to get shoes REALLY shiny.