Creed, Cult, and Code

Rake Fundamentals: FileLists

noreply@blogger.com (dalesmithtx) — Sat, 14 Jan 2012 23:06:00 +0000

In the last post, we created a rakefile that will copy a discreet set of *.bin files to a package directory for distribution using a single “publish” task. But it’s pretty verbose. We can refactor a bit to make the rakefile smaller, and make it handle an arbitrary list of *.bin files to be published to the /package directory using a FileList. A FileList is pretty simple – it’s just an array of file names. We’ll gather up all the *.bin files in the source/bin directory, and iterate through them to dynamically create file tasks for each of them and append each of those file tasks to the publish task’s prerequisite list. Here we go:

require 'rake'

BIN_DIR     = "source/bin"
PACKAGE_DIR = "package"

directory PACKAGE_DIR

BUILD_PRODUCTS = FileList[File.join(BIN_DIR, "**/*.bin")]
BUILD_PRODUCTS.each do |product|
packaged = product.sub(BIN_DIR, PACKAGE_DIR)
file packaged => product do
cp product, packaged, :verbose => true
end
task :publish => [PACKAGE_DIR, packaged]  
end

desc "publish *.bin files to #{PACKAGE_DIR}"
task :publish

We cut out a bunch of stuff we don’t really need, and all we’re left with on the command line is the publish task:

We don’t really care about all the individual file tasks, or the PACKAGE_DIR directory task, we just want our development team to care about the publish task. So we set BUILD_PRODUCTS to a list of all the *.bin files in the BIN_DIR, and stuffed them all into the publish task that appears in our task list. And to make it appear in the task list, we just give it a description after we get out of the .each do…end loop. The completed publish task works just like it did before, except that now it can handle a completely arbitrary list of *.bin files. Try it out – run “rake publish”, add a file called “file4.bin” to /source/bin, and then run “rake publish” again and see what happens.

Rake Fundamentals: directory tasks

noreply@blogger.com (dalesmithtx) — Sat, 14 Jan 2012 23:04:00 +0000

A build system is about building software. And on a purely mechanical level, the work of building software is largely about creating files and moving them around. The task keyword is the general workhorse for doing all kinds of things in Rake. But you can create specialized tasks focused on automating particular things. Rake comes with a couple of special kinds of tasks for managing directories and files.

The directory task

Remember how the keyword “task” is really just a call to a method named “task()”? Well the “directory” keyword is very similar – it’s really just a call to a method named “directory()”. “directory” is a special kind of task that has one main purpose: it creates the directory it names if that directory doesn’t exist. You don’t need to provide a do…end block parameter to a directory task, just a directory name. Here’s a little rakefile to illustrate what I mean:

require 'rake'

BIN_DIR       = "source/bin"
PACKAGE_DIR   = "package"

desc "create a #{BIN_DIR} directory"
directory BIN_DIR

desc "create a #{PACKAGE_DIR} directory"
directory PACKAGE_DIR

There are a couple of new concepts here: 1) BIN_DIR and PACKAGE_DIR are Ruby constants. By convention, Ruby constants are expressed in all caps with underscores. 2) The #{…} stuff is Ruby string replacement syntax. So here’s what we see when we look at the task list for this rakefile:

We have two tasks: one for creating a directory named “package”, and another for creating a directory named “source/bin”. Since we typically work with compiled languages in the .NET world, there will usually be a compile step in our build process that will take care of creating a /bin directory for us. But since we’re just pretending right now, I threw it in just for funsies. You can call these tasks from the command line, and since the directories they name don’t initially exist, rake creates those directories:

Making a directory is pretty simple – you just make the directory, and then you have the directory you wanted. That’s why you don’t have to pass a do…end block to the directory task – the directory task already knows how to create a directory. Ok, I hear what you’re saying: big deal. And you’re right, calling “rake package” from the command line is not particularly useful when you could just call “md package” on the command line. But directory tasks are very useful when you use them as prerequisites for file tasks.

Next up: file tasks

Rake Fundamentals: file tasks

noreply@blogger.com (dalesmithtx) — Sat, 14 Jan 2012 23:03:00 +0000

The file task

The “file” task keyword is a call to a method called, you guessed it, “file()”. Like the directory task, it’s purpose is to create the thing that it names. But making a file is a bit more involved than making a directory – you have to know what goes into the file when you make it. What’s the name and extension of the file? What’s the source for the data in the file? Should there be any kind of transformation, reformatting, or translation of the source data to the data to be saved in the file? What directory should you save the file in? You can provide all that info to the file task when you define it. Here’s some pseudo-code for a file task:

desc "copy source file to target file"
file target_file => source_file do
cp source_file, target_file
end

This isn’t a real file task, don’t try to run it. But what’s going on here? The name of this task is “target_file”, and it has a prerequisite called “source_file”. And if the file task decides that it’s supposed to execute the do…end block, rake uses the “cp” command to copy the file named “source_file” to a file named “target_file”. How does the file task decide that the do…end block needs to be executed? Two things factor into that decision: 1) if target_file doesn’t exist, then it obviously needs to be created, so the do…end block gets executed. 2) If the source_file is newer than the target_file, that means that the source_file has changed since the last time that the target_file was created, and the do…end block gets executed again so that the target_file will get refreshed with the changes in source_file.

Ok, let’s pretend. Let’s go back to our little rakefile we used to create directories. And let’s pretend that we have a source/bin directory that contains some binary files that are the result of compilation – we’ll call them “file1.bin”, “file2.bin”, and “file3.bin”. And furthermore, let’s pretend that we want to package those files up for distribution. We can write some file tasks to make that happen:

require 'rake'

BIN_DIR = "source/bin"
PACKAGE_DIR = "package"

desc "create a #{BIN_DIR} directory"
directory BIN_DIR

desc "create a #{PACKAGE_DIR} directory"
directory PACKAGE_DIR


desc "copy file1.bin to package"
file "package/file1.bin" => [PACKAGE_DIR, "source/bin/file1.bin"] do |t|
cp t.prerequisites[1], t.name, :verbose => true
end

desc "copy file2.bin to package"
file "package/file2.bin" => [PACKAGE_DIR, File.join(BIN_DIR, "file2.bin")] do |t|
cp t.prerequisites[1], t.name, :verbose => true
end

desc "copy file3.bin to package"
file "package/file3.bin" => [PACKAGE_DIR, File.join(BIN_DIR, "file3.bin")] do |t|
cp t.prerequisites[1], t.name, :verbose => true
end

And here’s our task list now:

In our file “package/file1.bin” task, there are two prerequisites: PACKAGE_DIR and “source/bin/file1.bin”. If we execute “rake package/file1.bin”, the first thing that will happen is the package directory will get created since it doesn’t already exist. And since package/file1.bin doesn’t exist either, our do…end block will get executed. That do…end block looks a bit different than anything we’ve seen so far, but it’s really not that complicated. Just like a lambda in c#, you can pass parameters to a do…end block in Ruby – in this case |t| represents the file task, and we’re passing it into our do…end block so that we can have access to some info about the task, particularly the prerequisites list and the name of the task. “cp t.prerequisites[1], t.name, :verbose => true” is very similar to the “cp source_file, target_file” line from the pseudo-code file task above. In this case, the source_file is “t.prerequisites[1]” – in other words, the source_file is “source/bin/file1.bin”, which is the value in element 1 of the file task’s prerequisites array. The target_file is “t.name” – in other words, the target_file is “package/file1.bin”, the name of the file task. And the “:verbose => true” thing just means “tell me what you’re doing when you copy this file.” If we run this task, here’s what we get:

Before we run the task, there’s no package directory. After we run the task, there’s a package directory and it contains file1.bin. Cool.

The file “package/file2.bin” task looks a little bit different. Instead of a source_file prerequisite called “source/bin/file2.bin”, we’ve got this:

File.join(BIN_DIR, “file2.bin”)

File.join() is a convenient Ruby method for formatting string input into properly structured path+filenames. “source/bin” and “file2.bin” are appended together and separated by a “/” character, and the result is “source/bin/file2.bin”.

I see you rolling your eyes again: whooptie-do, we can make files from the command line. Yep, I agree, the way we’ve set up our rakefile so far doesn’t really give us a compelling reason to use file and directory tasks. Calling each file task from the command line seems really cumbersome. What if we had a “publish” task that published all three of our *.bin files to the /package directory in one fell swoop? Let’s add this to the end of our rakefile:

desc "copy file1.bin to package"
task :publish => "package/file1.bin"

desc "copy file2.bin to package"
task :publish => "package/file2.bin"

desc "copy file3.bin to package"
task :publish => "package/file3.bin"

It looks like we’re adding three “publish” tasks, but we’re really only adding one:

Ruby allows you to do some pretty fancy dynamic stuff, and rake takes advantage of that by allowing you to “re-open” a task that has already been defined and add some more stuff to it. In our case, we’re re-opening the “publish” task and adding a new prerequisite for each of our *.bin files. The result is a single publish task that copies all three *.bin files to the /package directory:

Ok, now we’re getting somewhere. Now if only one of our source/bin/*.bin files changes, only the changed file will get copied to the /package folder. Open up source/bin/file2.bin and put some random text in it, and then run “rake publish” again:

We’re making progress, but our rakefile is still way too verbose. We need to find a way to reduce the amount of code it takes to copy these files out to /package. And we should also be able to copy an arbitrary list of files, not just a discreet list we have to keep updating.

Next up: FileLists

Rake Fundamentals: tasks with prerequisites

noreply@blogger.com (dalesmithtx) — Fri, 13 Jan 2012 23:02:00 +0000

Rake tasks can have other tasks as prerequisites. That means that a tasks prerequisites are executed before the task itself when the task is called from the command line. Just like Nant, if you have a lot of small tasks you often run together, it’s convenient to roll them up into one task with prerequisites. Let’s use rake to rock out:

require 'rake'

desc "open guitar case and get guitar"
task :get_axe do
puts "opening guitar case"
puts "grabbing telecaster"
end

desc "plug guitar into amp"
task :crank_up do
puts "plugging into 1959 fender tremolux"
puts "turning up volume"
end

desc "play A chord"
task :play_a do
puts "playing A chord"
end

desc "play D chord"
task :play_d do
puts "playing D chord"
end

desc "play E chord"
task :play_e do
puts "playing E chord"
end

desc "bask in the glory of adulation"
task :take_bow do
puts "taking a bow"
puts "winking at the girl in the front row"
end

desc "give the people what they want"
task :rock_the_house => [:get_axe, :crank_up, :play_a, :play_d,
:play_a, :play_e, :take_bow]

This rakefile defines these tasks:

And you could call each of these tasks individually if you wanted to. But we want to rock the house, right? So all we need to do is call “rake rock_the_house”. According to the prerequisite list in the :rock_the_house task, rocking the house should consist of getting out our axe, cranking up, jamming some chords in this order: ADAEA, and bowing to a standing ovation. Let’s give it a try and see what happens:

Our rock_the_house task ran all the prerequisites, except it didn’t play all the chords we told it to play – we only played ADE, not ADAEA. LAME! That’s because rake keeps track of tasks it has executed, and by default will only execute them once. That might be cool for some tasks, but we want to play the blues, so we have to re-enable our “play_a” task every time we execute it so that we can execute it again. Let’s fix our rakefile by creating a “play_the_blues” task that knows how to play our chords correctly:

require 'rake'

desc "open guitar case and get guitar"
task :get_axe do
puts "opening guitar case"
puts "grabbing telecaster"
end

desc "plug guitar into amp"
task :crank_up do
puts "plugging into 1959 fender tremolux"
puts "turning up volume"
end

desc "play A chord"
task :play_a do
puts "playing A chord"
end

desc "play D chord"
task :play_d do
puts "playing D chord"
end

desc "play E chord"
task :play_e do
puts "playing E chord"
end

desc "bask in the glory of adulation"
task :take_bow do
puts "taking a bow"
puts "winking at the girl in the front row"
end

task :play_the_blues do
Rake::Task[:play_a].invoke
Rake::Task[:play_a].reenable

Rake::Task[:play_d].invoke

Rake::Task[:play_a].invoke
Rake::Task[:play_a].reenable

Rake::Task[:play_e].invoke

Rake::Task[:play_a].invoke
end

desc "give the people what they want"
task :rock_the_house => [:get_axe, :crank_up, :play_the_blues, :take_bow]

Sometimes instead of calling a task as a prerequisite, you want to invoke it directly from within another task. Calling the invoke() method on Rake::Task[] is how you do that. Once you’ve called a task, you can reenable it to be called again by using Rake::Task[].reenable(). We’ve modified our “rock_the_house” task by calling our new “play_the_blues” task as a prerequisite. Notice that since we didn’t give our “play_the_blues” task a description, it doesn’t show up on the task list when you type “rake –T”. But it’s still available for use. Also, notice that we didn’t provide a do…end block to our “rock_the_house” task. Since we defined everything we need for rocking the house in our other tasks, we only needed to provide the “rock_the_house” task with prerequisites. Let’s see what happens now:

Perfect! All the chords get played in the right order. We’ve got a single task to call from the command line that can do all the things we want it to do.

Next up: directory and file tasks

Rake Fundamentals: rakefiles and tasks

noreply@blogger.com (dalesmithtx) — Fri, 13 Jan 2012 23:02:00 +0000

Ok, what is Rake again?

Rake is a collection of Ruby scripts that live deep within the bowels of your Ruby installation. Since you made sure you checked the box that adds the Ruby stuff to your PATH variable as you stepped through the Ruby installer wizard, you now have easy access to your Ruby installation and all of the special scripts it contains right from the command line. To make use of those Ruby scripts, you do a couple of things:

1) Create a rakefile, which is itself a ruby script containing named tasks you can run from the command line.

2) Run one or more of those tasks from the command line like so:

C:\sandbox\rakefun\> rake mytask

And what’s a rakefile?

That command you just issued told rake to look for a file called c:\sandbox\rakefun\rakefile.rb and execute a task called ‘mytask’. You can call the rakefile something else if you want to, but if you name it “rakefile.rb”, you don’t have to include the “-f my_special_rakefile_name_because_im_a_unique_delicate_flower.rb” switch on the rake command line call – just less to type if you stick to the convention. It’s easy to create a rakefile: open up notepad, type in your tasks, save it as “rakefile.rb”, and you’re done. No compiling. No real need for fancy IDE’s, just any old text editor will do. I like Notepad2, and Komodo Edit is another nice free one with Ruby syntax highlighting. So, what exactly is in a rakefile?

tasks

The fundamental building block of a rakefile is the “task”. Here’s a hello world rakefile that has one task in it called “:say_hi”.

require 'rake'

desc "My first rake task"
task :say_hi =>[] do
puts "Hello, dude!"
end

Ok, I fudged a little bit: when you open your editor to create your rakefile, you should actually require ‘rake’ at the beginning of the script. This tells Ruby to find the rake.rb ruby script and pull it into your rakefile when Ruby parses it. Ruby parses your rakefile any time you make a call to it with the rake keyword on the command line.

Rake provides a keyword called “task”. The task keyword is actually just a call to a method named “task()” that lives somewhere in the rake.rb ruby script. But through the magic of Ruby, the task() method call in your rakefile is formatted as you see above. Takes a little getting used to. Every time you call a task in your rakefile, Ruby parses the entire file, and all the task() method calls get executed. But don’t worry – as each task() method call is executed, Ruby is just looking through the rakefile to gather up the name of each task, and the code that Ruby should run when that task name is called from the command line. So if we had “:task1” and “:task2” in our rakefile, and we called “rake task1” from the command line, Ruby would know that we have both :task1 and :task2 available, but it would only run the code associated with task1.

There are two arguments being passed to task(), and if you’re not familiar with Ruby, they’re a little hard to distinguish:

1) The first argument is “:say_hi =>[]” – This is a Ruby hash object, which is just a collection of key/value pairs. In this case the hash contains only one key/value pair. The key is the symbol “:say_hi”, which by convention becomes the name of the task. The value is “[]”, which is Ruby parlance for an empty array. In more complex tasks, this array would contain the names of other tasks which should be prerequisites to this task. Ruby is pretty forgiving, and rake takes advantage of that, so if you have no prerequisites you don’t actually have to include the “=>[]” part; and when you have one or more prerequisites, you can exclude the brackets and just supply a comma-separated list of task names.

2) The second argument is this highlighted block of code starting with “do” and ending with “end”:
task :say_hi =>[] do
puts "Hello, dude!"
end
A code block is a special Ruby construct that you can think of like an anonymous method or a lambda. When you call a rake task, rake first executes all the prerequisite tasks you listed in the array in the first argument, and then executes the code in the do…end code block. If you only want to run prerequisite tasks without executing any other code, just don’t include a do…end code block.

The :say_hi task is called from the command line like this:

Get a list of tasks with rake -T

Tasks decorated with a “desc” are shown when you call “rake –T”, “rake –tasks”, or “rake –D” on the command line:

Tasks with no “desc” are not shown in the task list, but can still be called from the command line, or used as prerequisites for other tasks.

Next time: Tasks with prerequisites.

Rake. Huh?

noreply@blogger.com (dalesmithtx) — Fri, 13 Jan 2012 22:57:00 +0000

Lately I’ve been using rake at my office to build .NET solutions with Derick Bailey’s wonderful albacore gem. But I’ve had lots of questions from others on my team about rake:
1) What the heck is rake?
The official line on rake: it is a build system written in Ruby inspired by the make build system from the world of c. If that doesn’t really mean anything to you, just think of rake this way: it’s just a task runner. A rake script is a convenient place to script out small tasks that you have to do every day – tasks that don’t take long individually, but that you’re performing multiple times per hour while you are writing code. Automating those little rote tasks will save you time, and will cut down on the number of silly errors you get performing those tasks by hand.
2) A build system? Why do I need some fancy build system when I can just click the “Build Solution” menu option in Visual Studio?
Well first of all, having a build system outside of Visual Studio doesn’t keep you from using the Visual Studio build tools. A good build system should work alongside the IDE, not against it. But more importantly, when you have a complex solution with one or more deployable apps, some redistributable assemblies, and multiple test projects, you’ve got a lot of stuff to manage; a good build system enables you to manage all that stuff with a measure of convenience that Visual Studio just isn’t designed to provide.
3) Why rake instead of NAnt? Are you just trying to be cool?
NAnt is a perfectly useful build system, and I’ve used it for years. And with UppercuT, NAnt is certainly easier to use than it used to be. But it’s still just XML. Same thing goes for MSBuild. Ultimately you’re talking about filling out an XML configuration file. If I want a custom target type that does something NAnt (or MSBuild) doesn’t do out of the box, I have to use a real programming language to implement the guts of the target; so now I’ve got yet another project to manage. I’m sure there are people who love it and use it very successfully, but it’s just not my cup of tea. Not only is it not my cup of tea: it makes me hate tea. I’m a programmer, not a form-filler-outer. I want a programming language, not an XML configuration file.
4) We’re building .NET apps on Windows machines. Why automate with rake instead of PowerShell?
I’ve seen some very compelling demos of psake, another make-inspired build system, written in PowerShell. It’s certainly more to my liking than an XML-based build system. But PowerShell is vendorscript. I would rather spend time using a language that is a more transferrable skill, like Ruby.
Those are the “why” questions I get about rake, and my lame attempts to legitimize my desire to mess around with Ruby at work. I’m off and running on rake now, and the rest of the questions I get usually start with “how”. I’m hoping to write a few posts answering those questions, and I’ll update this post with links to other posts in the series as I go.

Installing Ruby and Rake

Before we talk about rake, rakefiles, and tasks, we’ll need a couple of things:
1) Ruby – rake is really just a set of Ruby scripts. And what do you need to run Ruby scripts? Ruby! The easiest way to get up and running with Ruby on a Windows box download the latest Ruby One-click Installer (version 1.9.2 as of this blog post), and just run it. Important: Make sure you check the box that adds the Ruby stuff to your PATH variable as you step through the installer wizard.

Once you’ve gotten through the wizard, open up a command prompt and type “ruby –v” to see the version number. You should see something like this:

If you see a message saying something along the lines of “ruby is not a recognized command”, just reboot. Windows just needs to deal with the PATH variable.
2) Rake – now that you’ve got Ruby installed, open up a command prompt and type

gem install rake

and hit enter. The “gem” keyword hooks you into Ruby’s package management system – you’re telling Ruby to grab the “rake” package from the RubyGems repository, and install it in your local Ruby installation. A bunch of stuff that won’t make a lot of sense will scroll by in the command window. But at the end of it, once you get back to a command prompt, you’ll be ready to run rake scripts.
3) A text editor – ok, three things. Notepad works just fine. If you want something fancier, there’s Komodo Edit, Notepad2, Notepad++ , etc. And if you wanna pay for a nice Ruby editor, JetBrains (the people behind the wonderful ReSharper) have a good one called RubyMine. I like RubyMine a lot, and I got lucky and picked up a copy for $29. Every once in a while they put it on sale, you just gotta check the website for it.

Next up: rakefiles and tasks

Announcing: the Dale Smith Valued Professional (DSVP) Program

noreply@blogger.com (dalesmithtx) — Fri, 06 Feb 2009 03:44:00 +0000

UPDATE: Scott Bellware has just made the grade as well. Welcome to the program, Scott!

UPDATE: The DSVP program welcomes Louis Salin. Way to go Louis!

Karl Seguin (among others) is a bit miffed about Microsoft's Most Valuable Professional (MVP) program. Or at least mystified. Seems that the rules of induction to the program have become a bit obscure. Why does Microsoft have the MVP program? According to Microsoft:

We present the MVP Award to thank individuals for their exceptional contributions to technical communities worldwide. When a community participant sees an MVP in a technical community, whether in a newsgroup, as a user group host, a conference speaker, or a respondent in forums, that community participant can be confident that the information shared by the MVP will be of the highest caliber and will help every user make the most of the technology.

So what kind of community contributions does Microsoft consider "exceptional"? What kind of information shared by MVPs in various forums does Microsoft consider to be "of the highest caliber"? I don't know - they don't really spell it out. But Microsoft is a publicly traded company, so I'm sure their primary goal is providing value for their shareholders. If I were in Microsoft's shoes I would consider information that benefits me in achieving that goal to be "exceptional" and "of the highest caliber".

I'm not in Microsoft's shoes. In fact, I'm not wearing shoes at all (I'm from Mississippi). And I have my own goals, chief among which is providing value for my employer and my customers so that I can earn a paycheck (hey, a guy's gotta eat). As it turns out, Karl Seguin has helped me achieve my goals over and over again by his activity in the community, as have many others. Those folks deserve an award!

So I hereby institute: <insert fanfare here> the DALE SMITH VALUED PROFESSIONAL (DSVP) PROGRAM. Why do I have the DSVP program?

Dale Smith presents the DSVP Award to thank individuals for their exceptional contributions to technical communities in which Dale Smith participates or trolls. When a community participant sees a DSVP in a technical community, whether in a newsgroup, as a user group host, a conference speaker, or a respondent in forums, that community participant can be confident that the information shared by the DSVP will be that which Dale Smith considers to be of the highest caliber and will help Dale Smith make the most of the technology.

Here are some questions you're probably asking yourself:

How do I become a Certified DSVP?

Well that's really kind of up to me, Dale Smith (see above). If you would like to be considered for the program, feel free to apply via the comment box below. We will consider your application carefully, and my legal team will contact you when a decision has been reached. I guess the main thing to remember here is this: some are born great, some achieve greatness, and others have greatness thrust upon them.

What does being a Certified DSVP get me?

First of all: Once a DSVP, always a DSVP. None of this you-have-to-renew-once-a-year stuff. That's just the kind of guy I am. (To be honest with you, this one is more about me avoiding paperwork than anything else.)

Second: I'll give you a warm smile and a hearty handshake if I ever run into you at a conference or something.

Third: You will have the right to use the letters D, S, V, and P after your name, like so -

Dale Smith, DSVP

See? Pretty spiffy, huh? If you use this baby after your name, you better believe that folks will know that when they see you in a technical community, whether in a newsgroup, as a user group host, a conference speaker, or a respondent in forums, that Dale Smith thinks you are one righteous dude.

Last, but not least: You're welcome to use this nifty badge on your blog, business cards, and any other self-promotional marketing materials you desire:

So why is the badge a cassette tape?

Microsoft is a lot cooler than I am. No, seriously, they really are. Granted, they sometimes exhibit some bewildering behavior in the way that they engage the development community. But the fact is, their achievements both in business and technology far outshine mine. So receiving an award from them, compared to an award from me, would be like getting the entire recorded output of the Replacements on pristine vinyl, still in the original unopened shrink wrap, plus all Paul Westerberg's and Chris Mars's solo material, records from Tommy Stinson's post-Mats bands Bash-n-Pop, Perfect, and even the new one from Guns 'n' Roses. While we're at it, let's throw in a high-quality bootleg of whatever you can find from Bob Stinson's post-Mats band Static Taxi.

In contrast, getting an award from me is like getting a self-made cassette from a local unsigned band. Nothing earth-shattering, mind you, but certainly earnest, sincere, charming. Definitely has its moments. And twenty years from now you'll probably run across it again in a box of long-forgotten tapes, and you'll throw it in the deck and think, "Oh yeah! I remember this! This was actually pretty cool!"

And now I'm going to induct Karl Seguin as the very first Certified DSVP. So here goes:

Yea and verily, be it known henceforth and forevermore that Karl Seguin is hereby Certified as a Dale Smith Valued Professional (DSVP) in the region of Ottawa, Ontario. Oh, what the heck! Let's make Karl's jurisdiction all of Canada! Congrats, Karl!

Share this post :

Refactoring Legacy ASP.NET Code-Behind with ReSharper

noreply@blogger.com (dalesmithtx) — Tue, 14 Oct 2008 05:34:00 +0000

I've been on a refactoring kick lately. And with the state of the legacy code at my office, I'll be refactoring for a very long time to come. This is a write-up of a refactor I did at work, altered enough so that I don't violate my NDA. But I think there's enough of the real story left to illustrate what I was talking about last time: you can indeed beautify even the ugliest code. A couple of items to note: 1) we're still on .NET 2.0 (no we haven't migrated to 3.5 yet - don't ask!), and 2) I'm not going to touch on testing much in this post. I really want to focus on the fact that you can positively affect some seriously messed up code with some pretty simple steps.

ParticipantDetails Refactor

We have a legacy ASP.NET web app that has some very tangled code-behind pages which need to be addressed. There are lots of items on the legacy app development wish list. Near the top, we have a strong desire to pull .NET 1.1 custom components out of our legacy app and replace them with our .NET 2.0 custom components. It would be wonderful if we only had to switch references to affect this change, but there are too many barriers in our code to a solution that simple. Another wish list item is testability, which means our code has to be restructured in such a way as to make it easily testable. If we tried to do all of this at one time we would most assuredly fail. Instead, we have to approach the problem with a series of smaller steps with an eye toward refactoring large pages over multiple iterations.

The ParticipantDetails.aspx.cs file is a good example of a code-behind file that has grown large and cumbersome: it has 3384 lines of code in it. It has many long methods in it, the longest of which is GetParticipant() at nearly 900 lines. This method essentially does three things:

1) fetches participant info from the database,

2) formats that data for display, and

3) assigns formatted data to the appropriate controls on the page.

To deal with this page, and particularly long methods like GetParticipant(), I approached it with three goals for this iteration:

1) make the methods much smaller, each focused on a single task, and therefore more easily readable and maintainable,

3) move the persistence coupling entirely out of this page, and instead couple the page to a set of Data Transfer Objects, and

2) apply the MVP pattern to this page to move as much code as possible into more testable classes.

I used ReSharper extensively for this refactor, particularly the Extract Method feature.

Small Methods

At 900 lines, GetParticipant() is extremely difficult to read, and even more difficult to modify correctly. It's easy to believe that the primary purpose of writing code is to allow the developer to give operational commands to a computer. We have to change our thinking here: that's the secondary purpose. The code we write is a living document that contains business information. The primary purpose I have when writing code is to create a document that allows me and you and everyone of our developers to communicate about how our company does business. A 900 line method conceals that information by adding noise. We reduce that noise and strengthen the real message of our code by separating concerns into multiple methods and classes. (By the way, this has the nice side effect of breaking dependencies and reducing coupling, which will make our code much easier to change in the future.)

Granted, we will end up with "class explosion". But the alternative is what we have now: "method bloat". A code base with many small classes containing small methods is much easier to maintain than a few huge classes with very long methods. How long is too long? I like to be able to see every line of a method on one screen. I have a rule of thumb called the "head rule": if I can't fit the whole method in my head, it's too long. How much can I fit in my head? Well, if I'm looking at the method on my screen and I hold my head next to it, if the method is longer than my head then it's too long. J

Data Transfer Object (DTO)

A Data Transfer Object (DTO), as the pattern is described by Martin Fowler, is "an object that carries data between processes in order to reduce the number of method calls". A DTO contains nothing but simple properties, no business logic inside the getters and setters for each property, and no methods at all. I used ReSharper to help me create a DTO called ParticipantDetailsDTO.

I started by declaring an ParticipantDetailsDTO variable at the top of the method. ReSharper immediately notices that I don’t have a class called ParticipantDetailsDTO in my solution and turns the new class name red. When put my cursor on the class name and click Alt+Enter, a menu appears that offers to create a new ParticipantDetailsDTO class for me.

I lucked out a bit when it was time to fill out the DTO. Most of the controls on the page are hydrated from private variables rather than directly from the Business 1.1 objects. My next step was to delete the declarations of those private variables. When I did that, ReSharper turned the variable names red wherever they appeared in the method.

Then, I prefixed every bad variable with “participantDetailsDTO”. Resharper asked me if I wanted to create a new property in ParticipantDetailsDTO called “strAsstEmail”. I took Resharper’s advice, and I worked my way through the whole method this way, filling out the ParticipantDetailsDTO class with new properties as I needed them. I also changed the property names to make them a bit more readable: e.g., strAsstEmail became AssistantEmail. Since the participant concept contains collections of other things (like Groups, Jobs, Specialties, etc.), I ended up needing several other DTOs. ParticipantDetailsDTO now contains List<T> properties for those collections. At the end of this process, all the controls on the page were dependent on DTOs rather than individual private variables. I had created a seam - I'm sure I'm not using that term as strictly as Michael Feathers intended, but I think the idea is similar: a specific place in my class meant to be moved or otherwise modified without affecting the rest of the class.

From there, still in the page code-behind, I started pulling similar code together: anything that was concerned with hydrating participantDetailsDTO got moved into a separate method. Same with all the other DTOs: each got its own method. This was a bit tricky. Sometimes I ran into code that decided how certain property values should be set. I had to be careful to preserve this code. But at the end of it, I had a number of methods that were all about hydrating the participantDetailsDTO and its collections. So I put them all into a class called ParticipantDetailsDTORepository and moved that class into the Vega.Common assembly. I also created an interface for it called IParticipantDetailsDTORepository – more about that in a minute. I ended up with something like this:

This is just a quick sketch, but I think you can see the bones of the design. This implementation of the IParticipantDetailsDTORepository works only with the .NET 1.1 components. IParticipantDetailsDTORepository contains a method called GetParticipantDetailsDTO(int participantId). When the time comes to switch this page over to the .NET 2.0 Business Components, we’ll write a new implementation of this repository interface that pulls participant info from the BC components. That should be a goal in our next iteration.

Model View Presenter (MVP)

So we’ve moved our participant fetch logic out of the code-behind. And obviously the code that assigns values to page controls has to stay in the code-behind (or does it?). But I see no reason for the data formatting code to remain here. This is where the model view presenter (MVP) pattern comes in. I declared an empty IParticipantDetailsView and made the page inherit from it. I also created a ParticipantDetailsPresenter class in Vega.Common – this is where I put all the formatting logic, and pretty much any other logic that wasn’t directly concerned with hydrating page controls. I made heavy use of Resharper’s Extract Method feature here. So now we also have something like this:

It is actually possible, and even desirable, to move control-hydration code into the presenter, but I didn’t go that far. I would love to go that direction and show it all under unit tests, but I didn’t have time in this post.

We're not done yet. There is still much more we can do to simplify this page. But the result so far is that the persistence-related code has been moved out into testable classes, the ParticipantDetails code-behind is now about 1200 lines instead of more than 3300, the code is much easier to read and understand, and we have an upgrade path to more easily switch out our persistence mechanism when we're ready. Next time, I'll talk about testing to detect change to ensure that the DTO built from the new persistence mechanism is the same as from the original mechanism.

Share this post :

Technorati Tags: ASP.NET,c#,Patterns,Refactoring,ReSharper

NDepend, or a Young .NET Programmer's Illustrated Primer

noreply@blogger.com (dalesmithtx) — Sun, 28 Sep 2008 03:00:00 +0000

Bootstraps

I have said before that I have no axe to grind against Microsoft, and I stand by that. They set out long ago to have a computer on every desktop and Microsoft software running on every computer. They have gone a long way towards achieving that goal, and in the process they have brought value to more people than I can count. Since their inception they have produced operating systems, languages, and development tools that have allowed people without computer science backgrounds to learn how to program computers to do actual stuff.

Now, granted, Microsoft has promoted development techniques that are much more in line with their own marketing plans than with sound design principles. But I cannot think of a time during Microsoft's existence when information about sound design principles was unavailable, or when Microsoft has ever actively sought to squelch that information. And I'm old.

I guess my point is this: Microsoft has produced some really nice tools, and it's up to me as a developer to use those tools wisely. But it's also up to me to find other tools and techniques that help me to be more effective as a developer. I feel a constant call to improve myself as a developer. I also feel a call to watch old Twilight Zone episodes on YouTube. But that first call is still there, and I respond to it too. I certainly benefit from my efforts to learn and grow, and my team benefits from my efforts as well. And ultimately, so does my company.

Many companies I have worked for have thought of their developers as commodities, particularly those who use Microsoft technologies. Approaching hiring, training, and project management practices from a commodity perspective has lead to commodity behavior in many developers: one MCP is as good as another; it Microsoft didn't invent it, it can't be good; we're all "human resources" rather than "personnel".

If you're in this situation, I have good news for you: you can take the red pill. You don't have to wait for your employer to educate you about your chosen profession. You can take the grass by the roots and educate yourself. There are tons of resources out there for you. One of those resources is a great little tool called NDepend.

A Real-World Example

The purpose of NDepend is to give you views into the actual structure of your software, regardless of how you intended to design it, that you would otherwise be unaware of. By blindly following the herd rather than thinking about long term design consequences, we often end up with some silly, expensive situations. NDepend can help us pinpoint the details of those situations so that we can address them.

A while back Chad Myers posted about the hazards of having WAAAAAAYYYYYY too many projects in a single solution file. I have wanted to write a post on NDepend for a while now. Others have already written better overviews than I could produce. And the NDepend tool itself ships with a whole host of how-to's in its documentation. Instead, I want to write about how we use NDepend at my office to address problems like those Chad describes, and that will probably take more than one post.

At my office we definitely suffer from the malady Chad describes. Our problem started innocently enough: years ago, we thought that we should package our API so granularly that we could deploy different pieces of it in an easy and atomic way. Well, it has proven not to be easy, but it is certainly atomic. And not in the good way. As we have added to our codebase over the years, we kept following the idea of many granular assemblies, but we somehow lost sight of the goal of easy deployment, and we ignored our need for maintainability. We now have a single solution file for assemblies meant to be shared among multiple applications that has nearly 150 projects in it. NEARLY 150!!! How do you even start to address a situation like that? Step 1 is admitting you have a problem. So first, we'll consolidate our assemblies, and manage our code with namespaces and project folders. But that's the subject of another post.

Step 2 is finding dead code and eliminating it, and that's the subject of this post. My problem here is that I'm under an NDA, so I can't show you details of the real situation, although I would love to. Instead here's a very trivial example to illuminate a couple of concepts: download. At work, I've got a (HUGE!) set of shared assemblies, and a couple of apps that consume those assemblies. So my example contains code meant to represent a situation like that: the CouplingExample assembly is the stand-in for the shared assemblies, and the CouplingExample.ConsoleApplication and CouplingExample.UnitTests assemblies represent the apps that depend on our shared assemblies.

NDepend ships with a SQL-like scripting language called Code Query Language (CQL). CQL allows you to write custom queries about the assemblies you're analyzing based on several different kinds of code metrics. NDepend ships with a bunch of pre-built CQL queries to give you a good starting place for cracking into your code. Since I'm trying to kill dead code, the metric I'm particularly interested in is afferent coupling, or actually the lack of it. For CouplingExample, I want to know which methods in the CouplingExample assembly have no methods that depend directly on them. I'm interested in non-public methods - it's a pretty safe bet that any non-publicly accessible method in my assembly that has nothing depending on it is dead code, and can therefore be eliminated. But I'm also interested in public methods with an afferent coupling of zero. Since I know all the applications that consume my shared assemblies, I can include those app assemblies in the same NDepend project. I can narrow down the scope of my CQL query just by including an ASSEMBLIES list. I swiped NDepend's canned "Potentially unused methods" query, and bent it to my own bidding like so:

   1: // <Name>Potentially unused shared assembly methods</Name>

   2: WARN IF Count > 0 IN SELECT TOP 10 METHODS FROM ASSEMBLIES "CouplingExample"  WHERE

   3:  MethodCa == 0 AND            // Ca=0 -> No Afferent Coupling -> The method is not used in the context of this application.

   4:  !IsEntryPoint AND            // Main() method is not used by-design.

   5:  !IsExplicitInterfaceImpl AND // The IL code never explicitely calls explicit interface methods implementation.

   6:  !IsClassConstructor AND      // The IL code never explicitely calls class constructors.

   7:  !IsFinalizer                 // The IL code never explicitely calls finalizers.

My NDepend project contains the shared assembly and the application assemblies that consume it. But this query only looks at methods in the CouplingExample assembly. When I run the query, NDepend paints a pretty picture of my code for me. Here's a context map showing all the assemblies I analyzed, and highlighting the methods in the CouplingExample assembly that have no other methods depending on them, either internally inside CouplingExample, or externally from the UnitTests and ConsoleApplication assemblies:

You can easily see which methods have no other methods depending on them, the ones in bright blue (and conveniently named "Public_no_afferent_coupling()" and "Private_no_afferent_coupling()"). Back in real life, I used the query above with all 140+ assembly names in it pointed at my shared assemblies and the consuming app assemblies. Here's a scrubbed version of the resulting context map:

Look at that! Tangled up in blue! Literally THOUSANDS of lines of code we can just drop. What a great feeling. I ran this picture by people in our group who, unlike me, actually have authority to buy stuff. Almost immediately, they put a line item in the budget for 10 NDepend licenses. This thing sells itself. And I feel confident that once more of our developers have begun to use it, we'll end up buying a license for everyone in the group.

This one little query for dead code is just the very top snowflake on the tip of the iceberg. NDepend gives you a myriad of insights into how your code actually works, empowering you to make it better, and educating you on how to create better designs in the future. A really cool feature of NDepend is its integration with Visual Studio: if you include the .pdb files in the NDepend project, you can just double-click on a method to bring it up in Visual Studio. I'm a ReSharper nut - I think Patrick Smacchia hit the nail on the head when he said that what ReSharper does for you on a micro-level, NDepend does for you on a macro-level. But the code metric analysis NDepend offers also puts it in a different realm than a refactoring tool like ReSharper. I think these two tools make a very powerful team together. Next time, I'll talk a bit about how we are beginning to use ReSharper to address situations like this one that NDepend illuminated for us.

We are now (finally!) giving attention to cleaning up messy old code. As we move along, I hope to write about other examples of how we change our code after examining it with NDepend, so stay tuned. This kind of stuff isn't only for the uber-geeks, it's for the day-to-day programmer who wants to improve skills, improve code, and deliver better products.

Share this post :

Technorati Tags: ASP.NET,c#,NDepend,Patterns,Tools

Boba Fett, Greedo, and StructureMap

noreply@blogger.com (dalesmithtx) — Sun, 17 Aug 2008 06:24:00 +0000

"Austin, Texas. You will never find a more wretched hive of scum and villainy. We must be cautious."

These words were uttered by an inhabitant of the the wastelands around Austin. Shrouded in mystery, most people think he's nothing more than a crazy old wizard. He keeps to himself mostly, occasionally seen associating with the lowest sort of riff-raff, and forever spouting mumbo-jumbo about some bizarre religion he follows. But there are those who know his true identity, that he is in fact the legendary Jedi Obi-Wan Kejeremy.

Ahhh, forget it. I just can't keep up the extended metaphor anymore. In keeping with my last post, I was going to go into some long, labored Star-Warsy exposition about Jeremy's new padawans, Chad and Josh, and the work they've done with him on a secret weapon called StructureMap. But it's late, I'm tired, and I want to finish this post tonight, so let's just skip right to the point, mmmmm-kay? I took the code I wrote for the last post and used StructureMap to decouple things a bit further after reading through Chad's articles (here and here) as well as a bunch of stuff Jeremy has written about StructureMap. Since there are still those among us who are fashionably late to the .NET 3.5 party, I used StructureMap 2.0. I also thought a bit more about the design and changed some things around after looking at Josh's code (and, let's be honest, outright stealing some of his code). And no, I didn't write tests for this stuff, and yes, I know that makes me a lazy jerk. See sentence four in this paragraph.

So here's how the Program class changed:

   1: class Program

   2: {

   3:     private static void Main(string[] args)

   4:     {

   5:         Configure();

6:

   7:         IAppEngine appEngine = ObjectFactory.GetInstance<IAppEngine>();

   8:         appEngine.Run();

   9:     }

10:

  11:     private static void Configure()

  12:     {

  13:         StructureMapConfiguration.UseDefaultStructureMapConfigFile = false;

  14:         StructureMapConfiguration.BuildInstancesOf<IAppEngine>().TheDefaultIsConcreteType<AppEngine>();

  15:         StructureMapConfiguration.BuildInstancesOf<IOutputDisplay>().TheDefaultIsConcreteType<ConsoleOutputDisplay>();

  16:         StructureMapConfiguration.BuildInstancesOf<IStuffStrategy>().TheDefaultIsConcreteType<LitterOfKittens>();

  17:         StructureMapConfiguration.BuildInstancesOf<IDrinkingEstablishment>()

  18:             .TheDefaultIs(

  19:             Registry.Instance<IDrinkingEstablishment>()

  20:                 .UsingConcreteType<Cantina>()

  21:                 .WithProperty("name").EqualTo("Mos Eisley Cantina")

  22:             );

  23:     }

  24: }

I love it! That Configure() method allowed me to break almost every dependency. The only time I'm actually using the new keyword is in the AppEngine (lines 15 and 22), and if I weren't falling asleep I could probably figure out a way to get rid of it there too.

   1: public class AppEngine : IAppEngine

   2: {

   3:     private IDrinkingEstablishment _drinkingEstablishment;

   4:     private IOutputDisplay _outputDisplay;

5:

   6:     public AppEngine(IDrinkingEstablishment drinkingEstablishment, IOutputDisplay outputDisplay)

   7:     {

   8:         _drinkingEstablishment = drinkingEstablishment;

   9:         _outputDisplay = outputDisplay;

  10:     }

11:

  12:     public void Run()

  13:     {

  14:         GetANewPatron("Boba Fett");

  15:         _drinkingEstablishment.SetStuffStrategy(200, new ConfusionOfWeasels());

  16:         GetANewPatron("Greedo");

  17:         _outputDisplay.Get();

  18:     }

19:

  20:     private void GetANewPatron(string name)

  21:     {

  22:         IPatron patron = new BountyHunter(name);

  23:         _drinkingEstablishment.WelcomePatron(patron);

  24:         foreach (IStuff thing in patron.Basket)

  25:             _outputDisplay.Put(thing.DoSomething(patron));

  26:     }

  27: }

So, without further adieu, you can download my little experiment and peruse it to your heart's content if you just click right here. Laugh at it all you want to. I'll be asleep.

Share this post :

Technorati Tags: c#,Patterns,StructureMap,Star Wars

Boba Fett, Greedo, and the Strategy Pattern

noreply@blogger.com (dalesmithtx) — Sat, 16 Aug 2008 09:13:00 +0000

Bounty hunting is a difficult line of work. Think about it: 1) Jobs are generally consulting gigs rather than full-time employment. 2) You're brought in at the last minute, usually to clean up someone else's mess, under a lot of pressure to save the day. 3) There are long hours, difficult problems to solve, and any benefits or vacation days come out of your own back pocket. So give Boba Fett and Greedo a little respect. They're willing to go flying off to the seedy backwaters of the galaxy, at great personal expense, mind you, turning over every stone until they find the Rebel scum they've been told to bring in. All because the megalomaniacal creeps they work for run huge bureaucratic organizations filled with nothing but boot-licking sycophants and lackeys who can't seem to catch one measly smuggler and his smelly walking-carpet sidekick. And if they should happen to run across this smuggler, who knows what kind of lethal stunt this half-witted, scruffy-looking nerf herder is liable to pull to get away from them. Here's just one example:

Shocking, isn't it? I know. It's called the StrategyPattern, and if you're not looking out for it, well you might just end up with some brand new ventilation courtesy of Han's blaster. Here's how it works:

Let's say you find yourself in a particular context, like, say, a cantina on a desert planet. Bartender gives you a drink, and you're parched, so you reach for it. But wait!! Is that beaker really filled with good old Membrosia? How do you know nobody has slipped the bartender a couple hundred galactic credits along with a bottle marked "Membrosia", but which is really heavily spiked with carsunum? What does the bartender care? All he knows is he gets a free bottle and two hundred credits out of the deal - makes no difference to him. People keel over in his place all the time. Seems like a pretty good strategy for knocking you off, wouldn't you say?

Here's another strategy pattern scenario I bet you didn't think about:

Boba Fett is a bounty hunter.

   1: public class BountyHunter : ICantinaPatron

   2: {

   3:     private string _name;

   4:     private IList<IStuff> _basket = new List<IStuff>();

5:

   6:     public BountyHunter(string name)

   7:     {

   8:         _name = name;

   9:     }

10:

  11:     public string Name

  12:     {

  13:         get { return _name; }

  14:     }

15:

  16:     public IList<IStuff> Basket

  17:     {

  18:         get { return _basket; }

  19:     }

  20: }

He happens to walk into the Mos Eisley cantina on a day when they're giving away stuff to all the cantina patrons: today, it's fuzzy animals. (Don't ask me. Some corporate marketing idiot from the cantina's Membrosia distributor thought it would be a good promotional gimmick.)

   1: public class Cantina

   2: {

   3:     private int _bribe;

   4:     private StuffStrategy _stuffStrategy = new LitterOfKittens();

5:

   6:     public void AcceptBribe(int bribe)

   7:     {

   8:         _bribe = bribe;

   9:     }

10:

  11:     public void SetStuffStrategy(StuffStrategy stuffStrategy)

  12:     {

  13:         if (_bribe > 100) _stuffStrategy = stuffStrategy;

  14:     }

15:

  16:     public ICantinaPatron GetPatron(string name)

  17:     {

  18:         ICantinaPatron cantinaPatron = new BountyHunter(name);

  19:         _stuffStrategy.GetStuff(cantinaPatron);

  20:         return cantinaPatron;

  21:     }

  22: }

23:

  24: public abstract class StuffStrategy

  25: {

  26:     public abstract void GetStuff(ICantinaPatron cantinaPatron);

  27: }

28:

  29: public interface IStuff

  30: {

  31:     string DoSomething(ICantinaPatron patron);

  32: }

33:

  34: public interface IFuzzyAnimal : IStuff

  35: {

  36:     string Name { get; }

  37:     string MakeNoise();

  38:     string Play();

  39: }

40:

41:

So when Boba Fett takes his basket of stuff from the barkeep and opens it up to see what he got, he discovers a litter of adorable kittens named Blossom, Minty, Butterscotch, Cotton Candy, Blue Belle, Snuzzle, and Rainbow Dash.

   1: public class Kitten : IFuzzyAnimal

   2: {

   3:     private string _name;

   4:     private string _playmate;

5:

   6:     public Kitten(string name)

   7:     {

   8:         _name = name;

   9:     }

10:

  11:     public string Name

  12:     {

  13:         get { return _name; }

  14:     }

15:

  16:     public string MakeNoise()

  17:     {

  18:         return

  19:             "Hi, " + _playmate + "!  My name is " + _name +

  20:             ", and I'm a kitten!  Meow!  prrrrr  prrrrrrrrrrrr";

  21:     }

22:

  23:     public string Play()

  24:     {

  25:         return _name + " blinks her big grey eyes and paws " + _playmate + "'s finger adorably.";

  26:     }

27:

  28:     public string DoSomething(ICantinaPatron patron)

  29:     {

  30:         _playmate = patron.Name;

  31:         return MakeNoise() + "\r\n" + Play() + "\r\n";

  32:     }

  33: }

34:

  35: public class LitterOfKittens : StuffStrategy

  36: {

  37:     public override void GetStuff(ICantinaPatron cantinaPatron)

  38:     {

  39:         cantinaPatron.Basket.Add(new Kitten("Blossom"));

  40:         cantinaPatron.Basket.Add(new Kitten("Minty"));

  41:         cantinaPatron.Basket.Add(new Kitten("Butterscotch"));

  42:         cantinaPatron.Basket.Add(new Kitten("Cotton Candy"));

  43:         cantinaPatron.Basket.Add(new Kitten("Blue Belle"));

  44:         cantinaPatron.Basket.Add(new Kitten("Snuzzle"));

  45:         cantinaPatron.Basket.Add(new Kitten("Rainbow Dash"));

  46:     }

  47: }

Here's what happens when Boba Fett plays with each kitten, and it's just the cutest thing you've ever seen. Almost brings a tear to your eye:

Greedo is also a noble bounty hunter, but he has a dark secret: he just loves fuzzy, adorable kittens! He's so excited when he sees what Boba Fett got that he completely forgets about the Strategy Pattern! Oh no! Greedo beware! While Greedo is distracted, Han has slipped the barkeep a bribe along with another group of "fuzzy animals":

   1: internal class Program

   2: {

   3:     private static Cantina _cantina;

4:

   5:     private static void Main(string[] args)

   6:     {

   7:         _cantina = new Cantina();

8:

   9:         GetANewPatron("Boba Fett");

10:

  11:         _cantina.AcceptBribe(200);

  12:         _cantina.SetStuffStrategy(new ConfusionOfWeasels());

13:

  14:         GetANewPatron("Greedo");

15:

  16:         Console.Read();

  17:     }

18:

  19:     private static void GetANewPatron(string name)

  20:     {

  21:         ICantinaPatron patron = _cantina.GetPatron(name);

  22:         Console.WriteLine(patron.Name + " enters the cantina");

  23:         foreach (IStuff thing in patron.Basket)

  24:             Console.WriteLine(thing.DoSomething(patron));

  25:     }

26:

  27: }

28:

  29: public class Weasel : IFuzzyAnimal

  30: {

  31:     private string _name;

  32:     private string _playmate;

33:

  34:     public Weasel(string name)

  35:     {

  36:         _name = name;

  37:     }

38:

  39:     public string Name

  40:     {

  41:         get { return _name; }

  42:     }

43:

  44:     public string MakeNoise()

  45:     {

  46:         return

  47:             "Hi, " + _playmate + "!  My name is " + _name +

  48:             ", and I'm a weasel!  SSHHHHREEEIIIIKKKK!!!  HISSSSSSSS!!!!!";

  49:     }

50:

  51:     public string Play()

  52:     {

  53:         return _name + " rips " + _playmate + " a new orifice.";

  54:     }

55:

  56:     public string DoSomething(ICantinaPatron patron)

  57:     {

  58:         _playmate = patron.Name;

  59:         return MakeNoise() + "\r\n" + Play() + "\r\n";

  60:     }

  61: }

62:

  63: public class ConfusionOfWeasels : StuffStrategy

  64: {

  65:     public override void GetStuff(ICantinaPatron cantinaPatron)

  66:     {

  67:         cantinaPatron.Basket.Add(new Weasel("Lefty"));

  68:         cantinaPatron.Basket.Add(new Weasel("One Eye"));

  69:         cantinaPatron.Basket.Add(new Weasel("Sanchez"));

  70:         cantinaPatron.Basket.Add(new Weasel("Scar"));

  71:         cantinaPatron.Basket.Add(new Weasel("Ashes"));

  72:         cantinaPatron.Basket.Add(new Weasel("Blade"));

  73:         cantinaPatron.Basket.Add(new Weasel("Rainbow Dash"));

  74:     }

  75: }

What does poor Greedo get in his basket? That's right: a really nasty confusion of weasels (that's the right term for a collection of weasels; I looked it up) named Lefty, One Eye, Sanchez, Scar, Ashes, Blade, and (oddly enough) Rainbow Dash! Greedo flew halfway across the galaxy to bring Han back to Jabba, but instead here's what he gets for his troubles:

So what's the morale of this tale? If you're a galactic bounty hunter and you ever find yourself in a desert planet cantina that's giving away baskets of fuzzy animals, be super careful, because what you think is gonna be a litter of kittens might just turn out to be a confusion of weasels. And, oh yeah, the Strategy Pattern is a good way to achieve some nice decoupling in your design. But seriously, don't forget about the weasel part.

Share this post :

Technorati Tags: c#,Patterns,StructureMap,Star Wars

Tracking Technical Debt in ReSharper - Follow-up

noreply@blogger.com (dalesmithtx) — Sat, 07 Jun 2008 03:45:00 +0000

Wow! The good folks at JetBrains found me and gave me a link! Thanks guys!

If you remember, we're still in the land of waterfalls, where everything has a signature and an arbitrary deadline, and a long schedule littered with milestones instead of actual released software. While marching toward that deadline, we've built up a lot of techinical debt, and we've been tracking it in ReSharper for about a month now. Well the time has finally come when we think we can begin to pay off some of that debt. We decided that since we had finished all, or at least most, of the features we set out to build that we could afford to spend some time focusing on those items we could have implemented better during development.

Our tracking scheme paid off quite nicely. There was one refinement that helped some, a Live Template for a //DEBT tag, like so:

//DEBT - $type$.$member$ - $END$

The $type$ variable is set to the "Containing type name" macro, and the $member$ variable is set to the "Containing type member name" macro. Did the same thing for the //HACK and //TODO tags. We used the TODO Explorer to dump our //DEBT out to a list we could email around, and no matter how the list was sorted the type and member info made it easy to see where our //DEBT was.

I have to say, once we introduced the idea of tracking //DEBT right there in our code, it became really easy to convince other developers on our team to focus on completing features rather than get bogged down in endless optimization. A little switch flipped in everyone's head once we realized that we could rely on our //DEBT list to remind us of things we need to come back to again.

Share this post :

Parsing YAML files in Ruby - Part 2

noreply@blogger.com (dalesmithtx) — Thu, 05 Jun 2008 05:48:00 +0000

I wish I had a clip reel I could roll after a dude with a really deep voice said, "Previously on Parsing YAML files in Ruby". But I don't. So here's a link.

Ruby is Narnia. I spend my real life in c#, a perfectly serviceable language. I'm comfortable there, I kind of know my way around, and I've come to depend on it to make my living. But when I have a few spare moments here and there, I get to wander off into this magical fairy-land and have adventures with strange and wonderful creatures. Like the YAML. In case you forgot what our YAML looks like, here he is:

   1: ---

   2: shared paths:

   3:   build share : \\buildshare.mydomain.com\Builds

4:

   5: local paths:

   6:   references  : \references

7:

   8: custom assemblies:

   9:   - location: \Dev\Components\Business\Core\Trunk\Latest\Debug

  10:     assemblies:

  11:       - name : MyNamespace.Core

  12:         files:

  13:           - binary    : MyNamespace.Core.dll

  14:           - debug     : MyNamespace.Core.pdb

  15:           - document  : MyNamespace.Core.xml

16:

  17:   - location: \Dev\Components\Framework\Trunk\Debug

  18:     assemblies:

  19:       - name : MyNamespace.Framework.Core

  20:         files:

  21:           - binary    : MyNamespace.Framework.Core.dll

  22:           - debug     : MyNamespace.Framework.Core.pdb

  23:           - document  : MyNamespace.Framework.Core.xml

24:

  25: vendor assemblies:

  26:   - location: \vendor\DotNet Commons\Logging\2.0

  27:     assemblies:

  28:       - name : Dotnet.Commons.Logging

  29:         files:

  30:           - binary    : Dotnet.Commons.Logging.dll

31:

  32: testing assemblies:

  33:   - location: \vendor\Nunit\2.4.3

  34:     assemblies:

  35:       - name : NUnit.Framework

  36:         files:

  37:           - binary    : nunit.framework.dll

38:

  39:   - location: \vendor\Rhino.Mocks\3.3.0.906

  40:     assemblies:

  41:       - name : Rhino.Mocks

  42:         files:

  43:           - binary    : Rhino.Mocks.dll

  44:           - document  : Rhino.Mocks.xml

  45: ...

Last time I told you how easy it was to access data in *.yml files in Ruby. I've taken idea that a little further, and I cooked up this class:

   1: require 'yaml'

2:

   3: class References

   4:   attr_accessor :debug_mode

   5:   def initialize(references_file_name='references.yml',debug_mode=true)

   6:     @refs = open(references_file_name) {|f| YAML.load(f) }

   7:     @debug_mode = debug_mode

   8:   end

   9:   def shared_root_directory

  10:     @refs['shared paths']['build share']

  11:   end

  12:   def get_filenames(assembly_list_name, *file_types)

  13:     get_node(@refs, assembly_list_name) do |assembly_list|

  14:       assembly_list.each do |packing_list|

  15:         get_node(packing_list, 'assemblies'){|assembly| get_names(assembly, packing_list['location'],file_types){|filename| yield filename}}

  16:       end

  17:     end

  18:   end

  19:   private

  20:   def concatenate(*locators)

  21:     concatenated = String.new

  22:     locators.each { |locator| concatenated << (locator =~ /\A(?!\\)/ ? '\\' : '') << locator.sub(/\\\Z/, '') }

  23:     return concatenated

  24:   end

  25:   def get_names(assembly, path,file_types)

  26:     get_node(assembly, 'files') do |file|

  27:       parse_filenames(file,file_types){|filename| yield concatenate(shared_root_directory,path,filename)}

  28:     end

  29:   end

  30:   def get_node(data_store, find_key)

  31:     yield data_store[find_key] if data_store.kind_of? Hash

  32:     data_store.each{|node| get_node(node, find_key){|subnode| yield subnode}} if data_store.kind_of? Array

  33:   end

  34:   def parse_filenames(file_node,file_types)

  35:     file_node.keys.each {|key| yield file_node[key] unless filter(key,file_types)} if file_node.kind_of? Hash

  36:     file_node.each{|element| parse_filenames(element,file_types){|value| yield value}} if file_node.kind_of? Array

  37:   end

  38:   def filter(key,file_types)

  39:     (!@debug_mode && key=="debug") || (!file_types.include?(key) unless file_types.empty?)

  40:   end

  41: end

With this References class, you can do something like this (pay attention - here's where it starts to get cool):

refs = References.new
refs.get_filenames("custom assemblies","binary"){|filename| puts filename}

And you get something like this:

\\buildshare.mydomain.com\Builds\Dev\Components\Business\Core\Trunk\Latest\Debug\MyNamespace.Core.dll
\\buildshare.mydomain.com\Builds\Dev\Components\Framework\Trunk\Debug\MyNamespace.Framework.Core.dll

Let's start with get_node() on line 30. This method is an iterator. I don't know why, but it took a long time for the lightbulb to go off in my head over Ruby's usage of the yield keyword. Turns out, it works just like all the Ruby books say it does. Really, why would they lie? In this case, on line 31, we're getting the value located in an element in the data_store hash picked out by the find_key variable, and yielding that value back to the calling method. And that calling method better have a code block to execute once it receives a value, or we're gonna get a big ol' runtime exception. For the get_filenames() call in our script, on line 14 we're saying, "Look in the top-most hash in the references.yml file and find me a node with a key called 'custom assemblies'". Remember: the way our YAML file is laid out, it's just a big, weird hash of arrays and hashes. We have to write code to ferret out the info we want, and in this case ultimately we want a list of filenames.

There's another interesting thing happening on line 31. There's an if statement at the end of the line. If you tried to get away with something like that in c# land, they'd lock you up and throw away the key. Ahh, but here in Narnia, animals talk, trees walk, and all sorts of silly things happen. You can even say "hey, do this thing if this other thing is true", they way people do. No fussy brackets, or parentheses, or overly strict formatting rules to worry about. Line 31 takes care of the case when data_store is a hash. If data_store is not a hash, it's an array of hashes, and we take care of that on line 32, using a little recursion magic to get at the hash in each element of the array.

I think of the contents of 'custom assemblies' as an assembly_list, and each assembly_list contains packing_lists, each with a location and a list of assemblies at that location. Each assembly can have more than one file associated with it - in this case I've listed the binary dll, the debug symbol pdb file, and the xml document associated with our custom assemblies. I'm asking References to get just the binary files in 'custom assemblies'. Now that I've got the 'custom assemblies' node, I already know that the assembly_list is an array, so I can just iterate through it with .each to get each packing_list. (That's the reason I wrote get_node() in the first place - as I was learning about YAML and Ruby, I wasn't sure what object types I was dealing with as I drilled down through the YAML file. I could probably simplify the get_node() iterator now that I understand the structure of the file better, but I'll save refactoring for another time.) A packing_list is a hash containing a 'location' that can have multiple 'assemblies'. Line 15 says, "Get me the filenames for every assembly in this packing_list, and I'm really only want the ones that match this list of file_types".

The * in front of file_types in the get_filenames() signature makes it an optional parameter. You don't have to specify the type of file you're looking for, and if you don't then you get back everything. But if you do specify a list of file_types, that list is used in the filter() method, which is called on line 35. Another cool Ruby-ish way of saying something: using the unless keyword. Line 35 says, "Take a look at all the keys in the file_node hash, and give me back the file_node value for each key unless the key should be filtered out."

I'm hoping to put plain old Ruby classes and YAML together with Rake so that I can sweep angle brackets out of my life forever, and I'll post my progress as I learn. Now I'm sure that there are better ways of expressing these things in Ruby. But I'm new here. I'm still enjoying my Turkish Delight and hot tea. I still have a lot to learn about Narnia, but for now it's back to the real world.

Share this post :

Introducing Developer Testing Into an Existing Team - Project Manager Thoughts

noreply@blogger.com (dalesmithtx) — Sat, 31 May 2008 22:41:00 +0000

Last time, I posted our developer's thoughts on the answer to this question: What was the tipping point for you that helped you decide automated developer testing was a worthwhile thing?

Here's what one of our project managers thought:

dalesmithtx: I've asked some of our developers that question, but I'm curious about your perspective as a project mangler, err..., I mean manager

Project Manager: The past weeks on [our current project] have shown the value

Project Manager: for sure

Project Manager: The challenge is getting the business folks to agree on that value

dalesmithtx: What value have you been able to see?

Project Manager: We saw that we could refactor and not miss a beat

Project Manager: assumes that your project is going to have time to refactor. When you only get one shot at integration testing that's a challenge

Project Manager: too often we follow the path of (1) code in silos (2) come together for a few days of integration (3) jump into QA

dalesmithtx: right

Project Manager: in that case the value goes way down because any refactoring the team does is in their spare time as they fix bugs and prepare for launch

dalesmithtx: Do you think you are going to be able to sell it to the business folks? Or do you see a need to do so?

dalesmithtx: (from my perspective, as long as they're getting sausage, why do they care what happens in the sausage factory?)

Project Manager: my last point was it still has value on the NEXT project or even the next hotfix. It increases your chances for quality follow on releases

dalesmithtx: sure

Project Manager: understood but if they KNOW about it they are going to fight to give you less time as you're doing work that could be cut

dalesmithtx: I dig what you're saying

Project Manager: If you just build it in and don't draw attention to it ... then yes

Project Manager: build it into the schedule I mean

dalesmithtx: At some point when we have an hour or so, I would really like for the [our current project] and [our other current project] teams to sit down and talk through a "lessons learned" session on this stuff

dalesmithtx: Not so much a post-mortem specific to our projects,...

Project Manager: right

Project Manager: a technical seminar sorta

dalesmithtx: But a post-mortem about the development techniques we used in an agile setting and in a waterfall setting

dalesmithtx: pros and cons

dalesmithtx: right

Project Manager: yep I mean it had a cost in [our current project] but since the work so far has been so lop-sided on the UI side compared to the rest of the engineering folks, we had time

dalesmithtx: right - that's an important point...

dalesmithtx: I want to claim victory, but I want to claim it on solid ground, not by hiding behind latency elsewhere in the project

dalesmithtx: I guess I'm looking for a real measure of the value that developer testing has brought to us so far, and what we think we need to change if we expect to get more value out of it on future development

Project Manager: ok

Project Manager: yeah I agree I don't like hiding tasks

Share this post :

Introducing Developer Testing Into an Existing Team - Developer Thoughts

noreply@blogger.com (dalesmithtx) — Sat, 31 May 2008 22:31:00 +0000

My friend Chad Myers posted recently about Introducting Quality-first Notions Into an Existing Team. Since you are such a devoted fan of my blog, you undoubtedly know that we have recently introduced Test Driven Development, or at least automated developer testing, to our team in the context both a waterfall project and an Agile project. Chad's post made me interested to see what folks on our team thought about developer testing now that they have been doing it for a bit. So I’ve been asking folks what they think of developer testing, specifically whether or not they thought it was worth it and what it was that made them think that. My point in doing this is that I want to gain actual value from our testing efforts, and not just remain in the “testing enthusiast” camp. I, of course, am sold on the idea of developer testing, but I thought you would like to see some of the responses I got:

dalesmithtx: What was the tipping point for you that helped you decide automated developer testing was a worthwhile thing?_________________________________________________________

DEV 1: Well, I'd say there was no tipping point. It was more of a feeling of: I can't wait until we get this going. Here are my feelings.

- The last shop I worked in used it and it proved its worth over and over. I was the one who setup and ran the test scripts so I saw the effort through from beginning to end first hand.

- It's another means to increase our test coverage although it's not meant to be a substitute for other types of testing.

- It helps enforce more testing by developers. For those developers who have not been exposed to test driven development, it's a big change. It's easy to just write code but it's also risky. Test driven development allows the developer a chance to think things through before writing code.

- I like to see you smile.

dalesmithtx: Aww, that's so sweet!

DEV 1: heh heh

_________________________________________________________

DEV 2: when I ran nUnit and saw all the blinky green lights?

dalesmithtx: good point

_________________________________________________________

DEV 3: hmm...

DEV 3: i guess i'd have to say finding mistakes in code while writing tests, which saves you some time up front when you start smoke testing. it showed me that you are not just investing additional time - you're saving time in other areas, so the overall investment is only slightly more, but the benefits are far reaching.

dalesmithtx: Very cool

dalesmithtx: DEV 2's answer:

DEV 2: when I ran nUnit and saw all the blinky green lights

dalesmithtx: Yours is a bit more helpful

DEV 3: haha... that's a big one too... until you see all green, you hate testing :-()

DEV 3: :-)

dalesmithtx: yup

_________________________________________________________

DEV 4: I think the real selling point for me occurs when you later make some changes you don't anticipate will be problematic and then find out some the tests failed. If not for the testing, there would have been issues.

DEV 4: You can also refactor with much greater confidence.

dalesmithtx: DEV 2's answer:

DEV 2: when I ran nUnit and saw all the blinky green lights

DEV 4: I think he meant red.

dalesmithtx: :)

__________________________________________________________

DEV 5: yea for me it was the first time I broke a test

DEV 5: went oh rainbow

DEV 5: that saved me 2 hours

DEV 5: I transposed two strings

DEV 5: was supposed to be string str3 = str1 + str2;

DEV 5: instead I did

DEV 5: string str3 = str2 + str1

DEV 5: in one function

DEV 5: unit test caught it instantly

DEV 5: would have taken me at least 2 hours to get UI setup to test

dalesmithtx: yeah

dalesmithtx: Yeah, for me it was really hooking up automated testing with CI, which we haven't really emphasized here yet

dalesmithtx: At least not on our current project

dalesmithtx: As soon as it clicked with me that a failed test means a failed build, I got it

DEV 5: yea

DEV 5: I think DEV 7 has best def yet though

DEV 5: its used like double blind accounting

DEV 5: & for the same reason

DEV 5: chances are you won't make the same mistake in the same way both places

dalesmithtx: right, I like that

DEV 5: yea so do I

____________________________________________________________

DEV 6: hmmmm

DEV 6: for one confidence in your code of what it does and does not ...

dalesmithtx: Do you remember if there was a particular incident? Or was it more of a general sense, arrived at through multiple tests?

DEV 6: ... and knowing what you delivered in regard to the business rules in the spec ...

DEV 6: yea a general sense via tests

DEV 6: no ah hah moment :)

dalesmithtx: right

____________________________________________________________

DEV 7: Your and DEV 8's respect

dalesmithtx: :)

dalesmithtx: that ain't worth much

DEV 7: I have to be honest I did not do it as much as I should have

DEV 7: And let it slide by the wayside when the project got well under way

DEV 7: :(

DEV 7: I just lost it

DEV 7: your respect that is

dalesmithtx: :)

dalesmithtx: nah

DEV 7: So, I hope to win your argument I get more issues with my code :)

DEV 7: I am still interested in approaching code that way

dalesmithtx: What are the implications of introducing developer testing to a legacy environment?

DEV 7: Just felt very rushed through much of the project

dalesmithtx: sure

dalesmithtx: that's the reason I'm asking though - just wondering what it has really gained us so far, and what we would change in future development efforts to get more out of developer testing

DEV 7: I know I dropped it around the time I had issues testing DB calls

DEV 7: But I see that as soon as those calls are at least a call away thet get mocked out anyway

dalesmithtx: so that's in interesting point - getting tangled up in physical dependencies is definitely a stumbling block to widespread adoption

dalesmithtx: understanding techniques on how to deal with those situations would help, but we have to have a vision on why we should do this in the first place

DEV 7: More practice would have let me see that it's not such a huge issue

DEV 7: Cool

dalesmithtx: sure, absolutely

dalesmithtx: I'm also interested in how to communicate the vision of what testing brings to others in our organization

DEV 7: Well hopefully you can get some good examples out of [our current project] code

dalesmithtx: and [our other current project]

DEV 7: Leave it anonymous though, so people don't think that I cause so many bugs

dalesmithtx: LOL

DEV 7: hehheeh

___________________________________________________________

DEV 8: i just generally think automated developer machines (ADM) are very cool

DEV 8: but it was when Chad [Myers] came to [my former employer] and showed us the error of our ways. I was converted by an itinerant preacher

dalesmithtx: :)

Share this post :

My new favorite Resharper feature

noreply@blogger.com (dalesmithtx) — Wed, 14 May 2008 03:17:00 +0000

I love the Find Dependent Code menu option in ReSharper. If you could see me now you would see a blissed out smile on my face and a bunch of cartoon hearts and flowers shooting out the top of my head.

A huge ugly legacy application I work on consumes custom components, and these components change from time to time. I had to make such a change today, and I was worried about how to figure out where I was going to get roasted by the legacy app dragon. Once again, ReSharper to the rescue: all I had to do was right click on the assembly name in my references list and then click Find Dependent Code. After thinking about it for about a minute, ReSharper popped the Find Results window up with a list like this (I changed the names to protect the innocent):

More than 1400 lines of code affected. I'm not happy about that, but I am happy that I can sort by file name and get a really useful, drill-downable, clickable list of files I need to check out.
ReSharper! Run away with me!

Share this post :

Parsing YAML files in Ruby

noreply@blogger.com (dalesmithtx) — Tue, 13 May 2008 05:25:00 +0000

I've been messing around with rake lately, hoping to find a build tool that is fairly well documented, well-supported, and doesn't make me dig through a pile of angle-brackets. At work, we store all our third-party assemblies on a centralized share. So one of the first tasks in any build file is to copy third-party assemblies locally before you can compile. It makes sense to me to specify reference assemblies in a human-readable data file and then read them in at runtime using a custom-written class for the occasion. But don't forget: I'm on a mission to vanquish XML from my build process at all cost. A fool's errand perhaps, but my errand none the less.

Enter YAML. Simple and elegant, YAML dispenses with lots of overhead and requires just enough structure to make it perfect for config files. Here's an example:

   1: ---

   2: shared paths:

   3:   lib share   : \\MySharedServer\lib

   4:   vendor      : \vendor

5:

   6: local paths:

   7:   references  : \references

8:

   9: custom assemblies:

  10:   - location: \Dev\Components\Business\Core\Trunk\Latest\Debug

  11:     assemblies:

  12:       - name: MyNamespace.Core

  13:         files:

  14:           - output    : MyNamespace.Core.dll

  15:           - debug     : MyNamespace.Core.pdb

  16:           - document  : MyNamespace.Core.xml

17:

  18:   - location: \Dev\Components\Framework\Trunk\Debug

  19:     assemblies:

  20:       - name: MyNamespace.Framework.Core

  21:         files:

  22:           - output    : MyNamespace.Framework.Core.dll

  23:           - debug     : MyNamespace.Framework.Core.pdb

  24:           - document  : MyNamespace.Framework.Core.xml

25:

  26: vendor assemblies:

  27:   - location: \DotNet Commons\Logging\2.0

  28:     assemblies:

  29:       - name: Dotnet.Commons.Logging

  30:         files:

  31:           - output    : Dotnet.Commons.Logging.dll

32:

  33: testing assemblies:

  34:   - location: \Nunit\2.4.3

  35:     assemblies:

  36:       - name: NUnit.Framework

  37:         files:

  38:           - output    : nunit.framework.dll

39:

  40:   - location: \Rhino.Mocks\3.3.0.906

  41:     assemblies:

  42:       - name: Rhino.Mocks

  43:         files:

  44:           - output    : Rhino.Mocks.dll

  45:           - document  : Rhino.Mocks.xml

  46: ...

What I've essentially got here is a hierarchical collection of hashes and arrays.  So in Ruby all I have to do is this :

require 'yaml'
refs = open('references.yml') {|f| YAML.load(f) }

and I've got direct access in code to all my data. What threw me at first was the idea that there would be an easy XPath-like way to say "give me a list of all the output files in the custom assemblies node". Instead, you have to write some parsing code, but it turns out it's not that hard. Here's the Ruby code I wrote to answer my query:

   1: require 'yaml'

2:

   3: refs = open('references.yml') {|f| YAML.load(f) }

4:

   5: refs['custom assemblies'].each do |location|

   6:   location['assemblies'].each do |assembly|

   7:     assembly['files'].each {|file| if file['output'] then puts "        #{file['output']}" end }

   8:   end

   9: end

I'm sure there are much more elegant ways to write that code, and as I learn idiomatic Ruby I'll write better Ruby code. But for now, here's why this works: my little config file is basically just a big, weird hash with five nodes. The "shared paths" node contains a hash, or map in YAML terms, of 2 nodes: lib share and vendor. The "local paths" node contains a hash with one node. "custom assemblies" is different: it contains a list with two items, and each list item contains a hash with two nodes ("location" and "assemblies"). If we keep digging down, the "files" node contains an array of hashes - the sample above digs down to this level and prints the file name if the hash key is "output".

Share this post :

Tracking Technical Debt in ReSharper

noreply@blogger.com (dalesmithtx) — Wed, 23 Apr 2008 04:44:00 +0000

I love ReSharper. It's purely platonic. After all, I am a married man. But it's always there for me: my trusty little sidekick, my own personal Sancho Panza. Its array of helpful features is truly impressive: it enhances editing capabilities; it helps me organize the classes in my projects; it cleans up my code for me; it tells me when I'm missing references; it offers suggestions for more readable conditional statements; it's a floor wax, a dessert topping, and a gentle laxative.

One of my favorite ReSharper features is the To-do Explorer. It scans your code base filtering on comment tags you define ("//TODO", et al) and gives you a clickable sorted list of those items. It's nicer than the VS TaskList in that you can sort the results in different ways (my favorite being by namespace and type), and you can copy the results to the clipboard or save them out to a text file.

Since swinging into TDD at our office in the last few weeks, we've started taking the idea of Technical Debt very seriously. As we're working through our implementation, we recognize that there are some deadlines which will force us to make some compromises on design decisions. That's ok as long as we don't forget to go back and re-work those things later. We've found that an easy way to track those things is to mark them with the comment tag "//DEBT" and set up a ReSharper To-do Explorer filter for that tag. Then when we're planning our next phase, we've got a sortable, printable list of items we know we have to prioritize into the project plan.

Taking that idea a bit further, we decided to standardize on the following three code comment tags and create ReSharper To-do Explorer filters for each:

//HACK == a HACK is something we put in place knowing it was wrong to begin with, and knowing it has to be taken care of as quickly as possible.
//TODO == a TODO could be anything that we need to complete by the end of the current iteration.
//DEBT == a technical debt is a calculated decision to complete a feature in this iteration using a design we know we will need to refactor in a future iteration.

When we take a look at To-do Explorer, we get something like this:

So before the end of the current iteration, we know we need to clean up our HACKs and TODOs. And at the beginning of the next iteration, we can throw the DEBTs in with the requirements to be prioritized and worked into the iteration plan.

I'm sure there are other ways to track technical debt that offer more info, but this is a quick, easy, and cheap way.

Share this post :

Continuous Integration and You

noreply@blogger.com (dalesmithtx) — Wed, 23 Apr 2008 03:39:00 +0000

OK, so it's not really about you. It's about me. I had to have something to pique your interest though, didn't I? I wrote this up for my team at work a while back, and I thought I would share it with the universe. So here it is, universe. Hope you dig it.

Working Together

Creating software is fundamentally a creative act of communication. There are plenty of things to communicate about on any non-trivial software project:

Customers and end users must communicate with business analysts and designers about their requirements for the system.
Business analysts and designers must work with test engineers, and must use these requirements to describe the bar the system must clear to be acceptable to customers.
The development team must understand this specification and communicate with designers, and with one another, so that they can clear that bar quickly enough to satisfy customers and deliver true value to them.
And tons and tons of other stuff…

Poor communication can contribute real friction to a software project. And, as any major dude will tell you, friction can be a real drag. A primary goal of any software development team should be to reduce friction wherever it occurs in the development process.

In a traditional waterfall approach to managing software projects, stitching together each developer’s work into a single integrated project typically occurs towards the end of a development cycle. This step can be a long and unpredictable process, full of friction, and it can rapidly turn into a nightmare. If you think about it, this is really another communication issue: how do we communicate with one another about the work we have each done as individuals, and put it together so that it all works together seamlessly?

Benefits of Continuous Integration

It is important to remember that creating software is a complex process, and there are no silver bullets to ward off a certain amount of complexity. But we should simplify things where we can. Adopting the practice of Continuous Integration (CI) is one step towards simplifying our software development projects. What can CI buy us when we use it in a disciplined way?

CI can eliminate the need for a long, arduous, risky integration task at the end of a development cycle.
If we combine CI with good automated unit testing and code coverage metrics, we can make our projects practically self-testing. A good suite of unit tests executing a high percentage of the code base on every integrated build can keep the quality of the code from deteriorating as the development cycle progresses.
By working in short bursts and committing new code to the master build server often, defects that are introduced into the master build become easier to find and eliminate: you’ve only changed a small piece of code since the last time the system functioned properly, so you don’t have very far to look to find the defect you just introduced.
Anyone on the team can get the latest functioning code, build it, and test it locally with minimum effort.
At any time in the development cycle, everyone on the team knows precisely what works, what doesn’t, and where they are on progressing towards functional code for the iteration.
CI can facilitate enforcement of coding standards.
In short, the biggest umbrella benefits CI can buy us are better communication on the development team and reduced risk.

Practices of Continuous Integration

So what exactly is involved when working in a CI environment? What tools are needed? What do developers have to do differently? I know: reading a bunch of wordy blather[1] from yet another starry-eyed XP acolyte about how “this practice will change your life” is extremely tedious. So I drew you a picture. Lemme ‘splain:

CI Tools

This diagram is intended only to be an example of how a CI environment can be configured. There are many different ways to configure a CI server, and many tools you could use. In my diagram, I chose the following tools, some of which we already use at [my company]:

CruiseControl.Net – the CI server software
CCTray – A status notification tool for CruiseControl.Net
SubVersion – our source control system
Visual Studio – duh!
NUnit – an open source .Net library for creating running unit tests
NCover – an ~~open source~~ .Net library for measuring the percentage of code the unit tests actually cover when testing.
FxCop – an open source .Net library for enforcing coding standards

Most of these tools are open source, which means they are free* - that's a big asterisk there; the licenses for some of these products are changing. You could choose others which are true third party commercial applications, supported by third party commercial software vendors. But there is a wealth of knowledge documented in the .Net community at large for a CI environment configured like this:

These are the steps:

Individual developers on the team check new code into subversion.
CruiseControl.Net checks the source code repository on regular intervals for newly checked-in code.
When CruiseControl.Net detects new source code in the repository, it runs targets in the NAnt build script.
NAnt uses the latest source code from the repository on the build machine.
NAnt compiles the project using Visual Studio. If the project won’t compile, the NAnt script exits with a failure message, and CruiseControl.Net delivers a failure message to developers via CCTray.
NAnt runs all the unit test fixtures using the NUnit framework. If any individual test in any test fixure fails, the NAnt script exits with a failure message, and CruiseControl.Net delivers a failure message to developers via CCTray.
NAnt uses NCover to measure the percentage of code executed by the NUnit test fixtures. You can set a coverage threshold as a failable build step: if the coverage percentage does not meet the stated coverage standard, say 85%, the NAnt script exits with a failure message, and CruiseControl.Net delivers a failure message to developers via CCTray.
NAnt uses FxCop to check the code for compliance with coding standards. If it finds any non-compliant code, the NAnt script exits with a failure message, and CruiseControl.Net delivers a failure message to developers via CCTray.
Once the NAnt script finishes all its tasks, it exits with a success or failure message. CruiseControl.Net delivers the message to developers via CCTray. At the same time, CruiseControl.Net creates web pages on the build it just completed containing information from each step in the build process.
Members of the development team can check these web pages to see details on the build results.

Developer Tasks

There are a lot of things that happen automatically in the scenario I described above. Running an environment like that is like having a whole extra person whose job is to put everybody’s code together, regression test every build, check everybody’s code for compliance to coding standards, and report the status of all that back to everyone on the team; but you don’t have to increase your Mountain Dew budget for this extra person.

However, like just about everything else in life, you will only get out of CI what you put into it. You have to approach CI with a certain discipline, and that means developers have to do things a little bit differently. But the cost to developers is small, and the benefit to the quality and progress of the project is great.

Automate the Build

Somebody has to champion the task of creating the CruiseControl.Net configuration and the NAnt scripts. These are not trivial tasks. But once the first set of config files and build scripts have been created, they can be extended for new build tasks and used as templates for other projects. Ideally, the build server should be looking for newly checked-in code in a very short feedback loop, say a range from every 60 seconds to every 10 minutes. Structure the automated build process such that it performs tasks which are important to the development team, and reports on the results of those tasks.

Write Unit Tests

Test your code. First write tests for your code, then write some more tests, and finally write some tests. And while you’re at it, write some tests. I cannot stress enough how valuable unit testing will be when combined with a CI environment. Test fixtures and test coverage metrics will be the safety net you rely on to tell you the health of the code as you move through the development cycle. Testing and testability should be first class citizens among all the considerations involved in the design process. Every developer on the team should provide test fixtures for their code, and the results of these tests should be viewed as a measure of the health of the code. Decide on a code coverage standard early (85% isn’t bad), and enforce it throughout the development cycle.

Commit Early and Commit Often

A developer’s attitude towards committing code to source control should be much like Al Capone’s attitude towards voting: do it early and often. The quicker you can get code onto the build server, the quicker you know your code will integrate with everyone else’s code.

Do the Check In Dance

Didn’t know this was going to be a dance lesson, did you? Jeremy Miller, the Arthur Murray of programming, has documented what he calls “The Check In Dance”[2]. And it goes a little something like this:

Let the rest of the team know a change is coming if it's a significant update.
Get the latest code from source control.
Do a merge on any conflicts.
Run the build locally [using the same build script as the build server],[3] and fix any problems found.
Commit the changes to source control.
Stop coding until the build passes.
If the build breaks, drop everything else and fix the build.

Stupid Developer Tricks

Speaking of Jeremy Miller, he has also documented some good general tips for developers to follow in a CI environment. It is worth quoting him at length:

“Check in as often as you can. Try to reach stopping points as often as you can. This goes back to the basic agile philosophy of making small changes and immediately verifying the small change. When you're doing Test Driven Development you strive to keep ‘Red Bar’ periods as short as possible. The same kind of thinking applies to code check-ins. Make small changes and see the impact on the rest of the code immediately. Merging code will be less painful the more frequently a team integrates their code.
Avoid stale code. If you have to keep code out for any length of time, make sure you are getting everyone else's changes. Try really hard not to keep code out overnight. If you're using shared developer workstations, put some sort of sign on the workstation that there is outstanding code on the box. I've seen several XP zealots swear that they'll throw away any code left overnight. Personally, I think that's just a silly case of ‘I'm more agile than thou,’ but it's still a bad idea to leave code out overnight if you can help it.
Don't ever check into or out of a busted build. Checking in might make it harder to fix the build because it will cloud the underlying reason for the build, and you can't really know if your changes are valid.
Communicate and negotiate check-ins to the rest of the team. Frequently the complexity of a merge can be dependent upon who goes first. Some teams will use some kind of toy as a ‘check in token’ to ensure that there is never more than one set of updates in any CI build. Pay attention to what the rest of the team is doing too.
If you're working on fixing the build, let the rest of the team know.
DON'T LEAVE THE BUILD BROKEN OVERNIGHT. That's also an occasional excuse to your wife on why you're home late from work. Use with caution though.
Not every member of the team needs to be a full-fledged ‘Build Master,’ but every developer needs to know how to execute a build locally and troubleshoot a broken build. If you're suckered into being the technical lead, make sure every team member is up to speed on the build.
The best practice for effective CI is to perform the integration on a developer workstation before that code escapes into the build server wild. It's okay to break the build once in awhile. One of my former colleagues used to say that the CI build should break occasionally just to know it's actually working. What's not okay is to leave the build in a broken state. That slows down the rest of the team by preventing them from checking in or out. Even worse, somebody might accidentally update their workstation with the broken build and get into an unknown state. If you follow these dance steps, you can minimize build breaks and run more smoothly. Besides, it's embarrassing to have the ‘Shame Card’ on your desk.”

Conclusion

As I said above, there are no silver bullets for much of the complexity we face on software development projects. Continuous Integration is certainly not a silver bullet; but when used effectively, it can indeed improve communication and reduce risk significantly. As Martha says, “Continuous Integration: it’s a Good Thing.”

[1] My wife often accuses me of being tedious and pedantic, particularly because I tend to use words like “tedious” and “pedantic”.

[2] Jeremy Miller, http://codebetter.com/blogs/jeremy.miller/archive/2005/07/25/129797.aspx, 2005

[3] I added the [bracketed text].

True Tales of the South - Vol 1

noreply@blogger.com (dalesmithtx) — Wed, 16 Apr 2008 20:56:00 +0000

Returning to Austin recently from a friend's wedding in Athens, GA, Wife and I had a layover in Houston. While Wife was napping, I spotted a guy at our gate furtively picking his nose. I nudged Wife and pointed out the picker to her, but he spotted me spotting him. The jig was up. I whispered to Wife that if he got on the plane first, she was going to have to walk in front of me to be a human shield. Sure enough he was in first class. Wife made it past him as we walked by. But as soon as I got to him, he stood up rather suddenly. I startle easily, so I "busted a grumpy", as a friend likes to say. It was silent, swift, and deadly, like a Navy Seal, and I'm sure his freshly-cleared nostrils caught it in full bloom. Turns out he wasn't lunging for me though, he was just reaching for something in his carry-on bag. The end.

Actual Items - April 16, 2008 Edition

noreply@blogger.com (dalesmithtx) — Wed, 16 Apr 2008 19:17:00 +0000

Here's an actual code snippet from a user details page I saw recently: ... //Get Feedback
GetFeedback();
//Get Paid Invoices
GetPaidInvoices();
//Get Actions:
GetActions();
//Get Address
GetAddress();
GetOtherData(); ... This goes on for about 15 method calls. Way to go on adding those useful, useful comments in there! And then the call to the method named GetOtherData() isn't commented at all. Cracks me up.

Tools of the Trade

noreply@blogger.com (dalesmithtx) — Sun, 13 Apr 2008 03:25:00 +0000

I'm a programmer who is interested in much more than just putting in my eight hours a day and drawing my paycheck twice a month. I want to excel at creating software. Learning to do so will be a life-long pursuit sitting at the feet of masters who are kind enough to pass on their expertise. Standing alongside excellent works by Martin Fowler, Michael Feathers, Brian Marick and others, one of my favorite books on my shelf is "Hand Tools: Their Ways and Workings" by Aldren A. Watson. Mr. Watson is a Vermont woodworker and illustrator who has spent many thousands of hours with the tools of his own trade. He says this about his tools:

"In one sense, tools are simply things of steel and wood, attractive to the eye, perhaps even beautiful in their efficient lines, functional design, and appealing contrasts of texture and color. In another, it might be imagines that they only wait to be taken up and used, when they will then automatically perform with the precision that their appearance implies. This is an illusion. Tools can indeed be made to perform extraordinary tasks, sometimes with such impressive dispatch that they seem to have life of their own. However, it is more realistic to see that a tool has no more and no less than a high potentiality for capacity performance. At the same time each one has its own peculiar ways and workings, individual quirks of personality, if you like. These traits must be discovered, at times only through dogged trial and error, and the knowledge of them applied with persistent discipline and an attitude of acceptance, for the tool will not change its ways. When a tool is picked up and used in recognition of these limitations, then its full capability can be exploited to your purposes, and the two of you will work agreeably in tandem. Thus there is a sharp distinction between working with you tools and merely working them on wood. “To my way of thinking the most practical means of acquiring this intimate understanding of the ways and workings of a tool is to take apart, see how it is built and how its mechanism controls its performance. Sharpen the cutter iron, clean and oil the tool, and put it back together again. Then look into its adjustments, trying out each one of them on waste pieces of wood. Experiment, too, with the different handholds, and the stance of your feet to determine what effect they have on the ease and efficiency of using the tool. “All of these factors operate in a cyclical fashion. As the potentialities and limitations of a tool are explored and understood, the quality of work tends to improve; and along with it grows the confidence that even more professional procedures are possible. As the tool begins to show signs of functioning more nearly as it was designed to perform, you may perceive that he implications of the phrase ‘in good hands this tool is capable of the finest work’ is not after all beyond your reach.”

Test Driven Development in the Time of Dragons

noreply@blogger.com (dalesmithtx) — Fri, 21 Mar 2008 15:33:00 +0000

Well, the office is abuzz with excitement over TDD. I could not be more pleased! I am genuinely happy that we are actively moving toward embracing developer testing across all of our applications. I started this job seven months ago with the goal of introducing continuous integration and developer testing to the group, and through the efforts of myself and others, that day has definitely arrived. My next goal is to get our development and business stakeholders to embrace Agile project management. I think the path towards that goal is through developer testing. We are starting out on a new project now spanning multiple applications, and we have unit testing built into our development plans. That’s something to be truly excited about. But beware: There be dragons here!

The Waterfall Dragon Achieving widespread adoption of TDD in our office is still an uphill effort though. Our main obstacle is our current project management process: waterfall. In the minds of our business stakeholders (and many of our technical stakeholders), the way you create software is a four-step process: 1) Make all your decisions, both business and technical, up front. Include a decision on when the software will be delivered. 2) Have the development team go away for a few months and build something. 3) Get back together at a pre-determined date to compare what was built to a specification which is now out of step with what the business really needs. 4) Whip the development team for getting it wrong, no matter how much overtime they worked, and then release the product anyway. The waterfall process doesn’t really lend itself to an iterative, collaborative approach focused on coding business rules in testable code. And our business stakeholders (and many of our technical stakeholders) do not yet grasp the idea that a working suite of tests is a very valuable deliverable. Ideally, we would work directly with the business stakeholders, building the application up by delivering multiple small releases, each focusing on a very small set of features. Instead, we’re trying to cram some XP practices, TDD and continuous integration in particular, into a process that just wasn’t built to accommodate them. I don’t want to sound cynical though: I’m thankful we’ve at least been given the green light to use a test-driven approach in this project. I think over time, as our test suite grows to cover large swaths of our code base, we will be able to prove to our management that it will be much easier to accommodate changes, or at least that we can determine the impact of those changes much earlier than without the test suite. With a healthy code base, we’ll be in a much better position to embrace Agile development. The Legacy Code Dragon I think our second biggest obstacle is legacy code. Our code base stretches back through time, several years in some places, to a time when .Net development was still very new, and almost no .Net developers had even heard of automated developer testing. Code which seemed perfectly reasonable when it was first written has grown a bit gangrenous with age. So we’re starting out saddled with untestable legacy code. In this new project, we will create code we will share among a few applications, and we’ll make changes to those front-end applications too. We will test as much of our new code as possible, and we will learn how to deal with untestable legacy code along the way. Now the TDD fans among us have varying amounts of experience with test-first development, but no one is a TDD black-belt yet. Some of us have had exposure to TDD at previous gigs, and we’ve all read books, tried samples, attended code camps, and learned some very helpful techniques. But most of the code camp-style TDD presentations that I’ve seen assume the developer will be writing a new app from the ground up, with a completely supportive Agile process to nurture it’s growth and success. We need some advice on how to work TDD into an organization and a code base which have been around a while. Toward that end, I just ordered Working with Legacy Code by Michael Feathers. In the meantime, we’re starting by keeping Jeremy Miller’s First Rule of TDD in mind: “isolate the ugly stuff.” (By they way, if you haven’t read Jeremy’s blog, what are you doing here? Stop reading this drivel, and go read his stuff now.)

Next time, I’m going to look at designing and coding a user story in a legacy app.