Say you run across a piece of code like this:

1
2
3
4
5
6
7
8
9
10
11
12

public void ProcessOrder(Order order)
{
	// If the order is on hold, figure out why and get the next availability date.
	if (order.Status == OrderStatus.OnHold && order.OrderDate < DateTime.Now)
	{
		// <imagine complex logic to check reason here...>
		order.OnHoldReason = (result of complex logic above);
 
		// <imagine complex logic to get the next available date here...>
		order.NextAvailableDate = (result of complex logic above);
	}
}

So it’s usually not this obvious in real code bases, but almost every time I’ve run into a grouping of comments in this arrangement it could be boiled down into something this simple. Can you see the refactoring potential? It’s pretty easy - extracting some variables and methods based upon the text in the comment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

public void ProcessOrder(Order order)
{
	var orderIsOnHold = (order.Status == OrderStatus.OnHold && order.OrderDate < DateTime.Now);
 
	if (orderIsOnHold)
	{
		order.OnHoldReason = getOnHoldReason(order)
		order.NextAvailableDate = getNextAvailableDate(order);
	}
}
 
public string getOnHoldReason(Order order)
{
	return // <imagine complex logic to check reason here...>
}
 
public DateTime getNextAvailableDate(Order order)
{
	return // <imagine complex logic to get the next available date here...>
}

Like I said, it’s not much and it’s certainly not hard (a few keystrokes in Visual Studio, with or without ReSharper), but it moves the comments from sitting idly above the code, not participating, to being true first class citizens in the program in the form of variable and method names. It doesn’t guarantee they’ll be updated with the code if the logic changes in the future, but it gives them a lot better shot at it. I mean, there aren’t really developers out there lazy enough to update the intention of a variable or method and not change the name, right? Right?

1. Download the Windows Management Framework Core package for your setup
2. If your machine is something older than Windows 7 or Server 2008 R2, you’ll need to get the PowerShell IIS7 Snap-In
3. If your workstation/build server and target web servers happen to be on different Windows domains, you’ll need to run this one time on each client machine:

   1	Set-Item WSMan:\localhost\Client\TrustedHosts *

4. Run this command once on each server:

   1	winrm quickconfig

5. You’ll need to load the PowerShell Snap-In once on each client, which differs depending on which version of Windows you’re running. Anything older than Windows 7 or Server 2008 R2:

   1	Add-PSSnapin WebAdministration

   Windows 7 and Server 2008 R2 run:

   1	Load-Module WebAdministration

6. Check if it’s working properly by running this command on any version of Windows (you should see the IIS7 Snap-In listed):

   1	Get-Module -ListAvailable

7. Get credentials for accessing the remote server
8. Start running some remote commands on your web servers:

   1	Invoke-Command -ComputerName "webserver_computerName" -Credential $credentials_from_last_step -ScriptBlock { Add-PSSnapin WebAdministration; Stop-Website IIS_Site_Name }

It’s not really that hard once you get the proper packages installed and the permissions worked out, and since it’s so powerful and useful for scripting purposes it’s well worth the trouble. The available commands are awesome for use in automated deployment scripts.

You can learn more about the PowerShell Snap-In provider here, and at its download site here.

Until you look at that code a few months down the road and wounder what the hell you were smoking, and it takes you almost as long to decipher it again as it did to write it in the first place. All of a sudden saving those few extra lines of code don’t seem so smart, huh?

The simple fact of the matter is you spend more time maintaining code than you do writing it in the first place, so being more explicit in your code always trumps being clever to save a few lines. Always.

There’s the obvious places where people get clever, like algorithms or loops, but there’s plenty of other places too. Places where I wouldn’t really call it “being clever”, or at least I’m sure the original authors never thought they were trying to be clever when they wrote it. It was probably just quicker to write it in a certain way. For example, take this code:

1
2
3
4
5
6
7
8

var mappedEmployees = new List<EmployeeViewModel>();
 
foreach (var employee in _employeeRepository.All().Where(x => x.IsRetired == false && x.Salary > 100000))
{
	mappedEmployees.Add(_employeeMapper.Map(employee));
}
 
return View(mappedEmployees);

It’s not really hard to read, but it’s not really easy either. It might take you an extra second or two to figure out what’s going on when you first look at (even if you wrote it a few months ago), but multiply that by how many places you see code like this and how often you go back in to modify it (for new features, bugs, whatever). It adds up, quick. Written more explicitly, it might look something like this:

1
2
3
4
5
6
7
8
9
10

var mappedEmployees = new List<EmployeeViewModel>();
var nonRetiredHighEarningEmployees = _employeeRepository.All().Where(x => x.IsRetired == false && x.Salary > 100000);
 
foreach (var nonRetiredHighEarningEmployee in nonRetiredHighEarningEmployees)
{
	var mappedEmployee = _employeeMapper.Map(nonRetiredHighEarningEmployee);
	mappedEmployees.Add(mappedEmployee);
}
 
return View(mappedEmployees);

You might call it verbose, but I’d say it’s a net gain. Each line is doing one thing. Yon can step through and read it without mentally pulling pieces apart. None of this “OK, that’s the mapped object call there, and its return is going into the collection there, and the whole thing is looping through that query there”. Things are given names and methods aren’t nested inside each other.

Always be on the lookout for “clever” areas in your code. Be explicit. Try to stick to each line doing one thing so there’s no hidden surprises.

The Open/Closed Principle is the O in the nearly infamous SOLID set of design principles. The gist of the principle is that any given class should be open for extension, but closed for modification. In more practical terms, you should be able to make most classes do something new or different without actually changing a single line of code within the class itself.

That’s simple! Right? Ummm, sure. How, exactly, is a class supposed to be able to do more stuff without being modified? Well, there’s lots of ways, if you think about it. I mean, that’s sort of what inheritance and polymorphism were made for. There’s also other pretty neat ways, too. One of them shows the true beauty of inversion of control, and dependency injection frameworks.

Lets say you have a collection of customers. You need to loop through these people, running a few different checks on them (only preferred customers can carry a negative balance, credit cards on file aren’t expired, etc), and adding any resulting errors from those checks to another collection for display later. Nothing too terribly complicated.

Solving without considering OCP

First we have to load up the customers and send them on through:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

private static void Main(string[] args)
{
	var customers = get_customers_from_somewhere();
 
	var check_runner = new Check_runner();
	var warnings = check_runner.run_checks_on(customers);
 
	foreach (var warning in warnings)
	{
		Console.WriteLine(warning);
	}
 
	Console.ReadLine();
}
 
private static IEnumerable<Customer> get_customers_from_somewhere()
{						// database, webservice, whatever.
	return new[]
	       	{
	       		new Customer
	       			{
					name = "Joe Smith",
	       				credit_card = new Credit_card { is_valid = true },
	       				balance = 100,
	       				is_preferred = true
	       			},
	       		new Customer
	       			{
					name = "Nathan Hawes",
	       				credit_card = new Credit_card { is_valid = false },
	       				balance = 0,
	       				is_preferred = true
	       			},
	       		new Customer
	       			{
					name = "Melinda Plunkett",
	       				credit_card = new Credit_card { is_valid = true },
	       				balance = -100,
	       				is_preferred = false
	       			}
	       	};
}

The class running all the checks:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

public class Check_runner
{
	private static readonly IList<string> _warnings = new List<string>();
 
	public IEnumerable<string> run_checks_on(IEnumerable<Customer> customers)
	{
		foreach (var customer in customers)
		{
			check_that_only_preferred_customer_can_have_a_negative_balance(customer);
			check_that_on_file_credit_card_is_not_expired(customer);
			// additional checks in the future...
		}
 
		return _warnings;
	}
 
	private static void check_that_on_file_credit_card_is_not_expired(Customer customer)
	{
		if (customer.credit_card.is_valid)
		{
			return;
		}
 
		_warnings.Add("Credit card expired for customer: " + customer.name);
	}
 
	private static void check_that_only_preferred_customer_can_have_a_negative_balance(Customer customer)
	{
		if (customer.is_preferred || customer.balance >= 0)
		{
			return;
		}
 
		_warnings.Add("Negative balance for non preferred customer: " + customer.name);
	}
}

Pretty standard. Loop through the customers, calling a separate private method for each check you need to preform, adding a message for that check’s error to a collection that ultimately gets returned to the caller for display.

The problems with the first approach

At first blush, this way of running the checks might seem very simple and understandable, but it starts to break down for a few different reasons:

• New checks could get pretty complicated, requiring access to other expensive objects (repositories, web services, file I/O, etc). Even if only one check needed a certain dependency, the whole Check_runner class is now burdened with that dependency.
• Every new check requires you to open up the Check_runner class and making a modification. Opening a class and modifying it? That’s pretty much the definition of an OCP violation. Modifying a class always introduces the possibility for regression bugs. No matter how small the possibility or bug, they’re there.
• Testing this thing as it gets larger and larger is going to be a pain in the rear. It’ll also get much harder, especially if outside dependencies are brought in (having to setup multiple dependencies when the one check you’re testing doesn’t even use them isn’t fun, or clear to read later).

One possible solution

There’s a few different ways to go about fixing this. My suggestion would be to break each check into its own individual class, with the Check_runner taking them all in and looping through them, running each as it goes. It sounds a little more black-magicy than it really is. I’m going to show all the code first, then go over the benefits of an approach like this later on. Lets start by defining an interface for these check classes:

1
2
3
4
5

public interface ICustomer_check
{
	string buildWarningFor(Customer customer);
	bool failsFor(Customer customer);
}

Now we can define a single check, which knows when it fails for a given customer, and how to build a warning message for that failure. The check classes for the two checks that are ran above would be a simple conversion of the existing code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

public class Negative_balance_check : ICustomer_check
{
	public string buildWarningFor(Customer customer)
	{
		return "Negative balance for non preferred customer: " + customer.name;
	}
 
	public bool failsFor(Customer customer)
	{
		return (!customer.is_preferred && customer.balance < 0);
	}
}
 
public class Expired_credit_card_check : ICustomer_check
{
	public string buildWarningFor(Customer customer)
	{
		return "Credit card expired for customer: " + customer.name;
	}
 
	public bool failsFor(Customer customer)
	{
		return (customer.credit_card.is_valid == false);
	}
}

Now the Check_runner just has to loop through all of the ICustomer_check implementations and run them:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

public class Check_runner
{
	private readonly IEnumerable<ICustomer_check> _customer_checks;
 
	public Check_runner(IEnumerable<ICustomer_check> customerChecks)
	{
		_customer_checks = customerChecks;
	}
 
	public IEnumerable<string> run_checks_on(IEnumerable<Customer> customers)
	{
		var warnings = new List<string>();
 
		foreach (var customer in customers)
		{
			foreach (var check in _customer_checks)
			{
				if (check.failsFor(customer))
				{
					warnings.Add(check.buildWarningFor(customer));
				}
			}
		}
 
		return warnings;
	}
}

Again, pretty simple and focused. Where does that enumeration of ICustomer_check implementations come from though? The missing key: our dependency injection framework. I’ll use StructureMap for this example. After downloading that and referencing the assembly, we’ll modify our main method to set it up:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

private static void Main(string[] args)
{
	ObjectFactory.Initialize(y => y.Scan(x =>
	                                     {
	                                     	x.TheCallingAssembly();
						x.AddAllTypesOf<ICustomer_check>();
	                                     }));
 
	var customers = get_customers_from_somewhere();
 
	var check_runner = ObjectFactory.GetInstance<Check_runner>();
	var warnings = check_runner.run_checks_on(customers);
 
	foreach (var warning in warnings)
	{
		Console.WriteLine(warning);
	}
 
	Console.ReadLine();
}

We fire up StructureMap, telling it to scan the calling assembly and find all implementations of ICustomer_check. When we ask for an instance of Check_runner, StructureMap knows to provide all the implementations it found of ICustomer_check to Check_runner’s constructor argument in a list. Since this is the outer most edge of the application, we’ll interact with the dependency injection framework here instead of inside Check_runner.

Benefits

So perhaps other than the StructureMap related code (if you don’t already know the basics of it), nothing I’ve done here has really complicated the system. It’s still a few primitive classes working together in a fairly obvious way. What benefits do we gain from these changes though?

• Each piece of the system now has a single, specific responsibility. You can look at each check and quickly figure out what its purpose is. The runner simply takes in all the checks and runs them (funny how its name now follows its responsibility too).
• The check classes can now take in their own dependencies. Need an ICustomerRepository or ICustomerAccountService for something? List it in the constructor. Each check is getting pulled from the container, so their dependencies will get filled as well. Checks will also only take on what each one needs, as opposed to requiring dependencies they might not have before.
• With decreased responsibilities, each piece now becomes much easier to test. Supply a list of dummy checks and dummy customer to make sure the runner is doing its job. Same for the checks themselves. In fact, too many tests for a class is a smell that class is doing too much in the first place.
• The point of the article: no more OCP violations! Future requirements for different kinds of checks now become almost mind numbingly easy. Slap in a new class and implement ICustomer_check. That’s it - the container will take care of the rest. Virtually no possibility of introducing a regression bug and messing up one of the other checks by adding a new one.

Conclusion

One thing to remember when looking for OCP violations in your code base is that “closed for modifications” should be taken within context. Fixing bugs, adding complete new features, etc, will obviously require modifications to something. You’re not going to create every class in your system and never touch them again. Within reason, you should apply the Open-Closed Principle to your code as much as possible. It makes it simpler to understand on the micro and macro level once your familiar with some of the more common patterns, and it helps reduce the possibility of introducing bugs from future additions.

The code from this post is available here.

Solution: use our build script & build server to handle it for us.

We gave our domain peeps commit access to the repository - thankfully we’re still on SVN, as I’m sure their heads will explode when we switch to a DVCS. This provides nice versioning and accountability features if someone messes up (imagine that), and gives us a hook for the build server. All help files are contained in a hierarchy under a folder that’s appropriately named HelpFiles. I checked out just that folder from the source tree on their machines and gave them a quick commit/update spiel. We created empty HTML files for them, and they went about their way filling them all in.

Now on to the more interesting part, our build script. As I’ve mentioned previously, we’re using psake. Here’s the relevant properties and task:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

properties {
	$scm_hidden_dir = ".svn";
 
	$executing_directory = new-object System.IO.DirectoryInfo $pwd
	$base_dir = $executing_directory.Parent.FullName
 
	$source_dir = "$base_dir\src"
	$build_dir = "$base_dir\build"
	$build_tools_dir = "$build_dir\tools"
 
	$share_web = "wwwroot"
	$servers_production = @("server1", "server2")
 
	$security_user = "user_with_write_access"
	$security_password = "pa55w0rd"
 
	$tools_robocopy = "$build_tools_dir\robocopy\robocopy.exe"
 
	$help_folder = "HelpFiles"
	$help_local_dir = "$source_dir\$project_name.Web\$help_folder"
	$deployTarget_help = "$project_name\$help_folder"
}
 
task publish_help {
	foreach ($server in $servers_production)
	{
		$full_server_share = "\\$server\$share_web"
 
		exec { & net use $full_server_share /user:$security_user $security_password }
 
		& $tools_robocopy $help_local_dir $full_server_share\$deployTarget_help /xd $scm_hidden_dir /fp /r:2 /mir
 
		# See page 33 of the help file in the tool's folder for exit code explaination.
		if ($lastexitcode -gt 3)
		{
			Exit $lastexitcode
		}
 
		exec { & net use $full_server_share /delete }
	}
}

There’s an array of production server names, which we iterate over and use the net command built into Windows to map its wwwroot share using a different username & password than the current user (this allows the build server to run as an unprivileged user but still access needed resources).

Then we use the surprisingly awesome Robocopy tool from Microsoft, which is basically xcopy on steroids, to copy out the help files themselves. The xd flag is excluding the hidden .svn folders, the fp flag is displaying full path names in the output (for display in the build output from TeamCity later), the r flag is telling it to only retry failed file twice (as opposed to the default million times!), and the mir flag is telling it to mirror the source directory tree to the destination, including empty folders and removing dead files.

We can’t use psake’s built in exec function to run Robocopy, as exec only checks for non-zero return codes before considerng it a failure. Of course, just to be different, Robocopy only fails if its return code is above 3 (1 = one or more files copied successfully, 2 = extra files or folders detected, and there is no 3). So we check the return code ourselves and exit if Robocopy failed. We then delete the share, effectively making the machine forget the username/password associated with it.

With that done, we created a new build configuration in TeamCity and had it check the repository for changes only to the help file directory by adding +:src/Project.Web/HelpFiles/** to the Trigger Patterns field on the Build Triggers configuration step.

That’s pretty much it. Our domain peeps have been pretty receptive to it so far, and they love being able to edit the help files, commit, and see them live only a minute or two later. We loved not having to pull all that text from the database on each page load and not having to create editing/viewing/versioning/etc tools around such a process. It’s a win-win.

Books

1. Code Complete - Steve McConnell - Not started.
2. Patterns of Enterprise Application Architecture - Martin Fowler - Not started.
3. Applying Domain-Driven Design and Patterns - Jimmy Nilsson
4. Working Effectively With Legacy Code - Michael Feathers - Not started.

Tools/Techniques/Processes @ Work

• Move from SVN to Git (and learn more about Git in the process). - Learning about Git and bugging our sys admin about setting up Git, but haven’t actually started yet.
• Move from CC.NET to Team City for our build server.
• Build a more robust build script and management process - including production deployment and database migration scenarios. - Well underway.

Involvement

• Develop an idea I was given for an open source project and get it live to see what happens. - In progress.
• At least 24 blog posts (I’m not going to say 2 per month as I’m getting married this summer and I’m certain I won’t be able to maintain a schedule around it). - 4 down (ouch!).
• At least 3 feature/patch submissions to open source projects. - Not started.

Coding

• Get a version 1 out there on at least 1 of the 3 product ideas I have floating around. - Not started.
• Keep working on a good working knowledge of Ruby & Ruby on Rails (and use it to build the product mentioned above). - Playing and reading.

So-so. Lets see about next quarter.

To start with, you’ll want to make sure you have the latest versions of PowerShell (2.0) and psake. Here’s the basics of our build script:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

$ErrorActionPreference = 'Stop'
 
Include ".\functions_general.ps1"
 
properties {
	$project_name = "MainApplication"
	$build_config = "Debug"
}
 
properties { # Directories
	$scm_hidden_dir = ".svn";
 
	$executing_directory = new-object System.IO.DirectoryInfo $pwd
	$base_dir = $executing_directory.Parent.FullName
 
	$source_dir = "$base_dir\src"
 
	$build_dir = "$base_dir\build"
	$tools_dir = "$base_dir\tools"
	$build_tools_dir = "$build_dir\tools"
 
	$build_artifacts_dir = "$build_dir\artifacts"
	$build_output_dir = "$build_artifacts_dir\output"
	$build_reports_dir = "$build_artifacts_dir\reports"
 
	$transient_folders = @($build_artifacts_dir, $build_output_dir, $build_reports_dir)
}
 
properties { # Executables
	$tools_nunit = "$tools_dir\nunit\nunit-console-x86.exe"
	$tools_gallio = "$tools_dir\Gallio\Gallio.Echo.exe"
	$tools_coverage = "$build_tools_dir\ncover\ncover.console.exe"
	$tools_coverageExplorer = "$build_tools_dir\ncover_explorer\NCoverExplorer.Console.exe"
}
 
properties { # Files
	$solution_file = "$source_dir\$project_name.sln"
 
	$output_unitTests_dll = "$build_output_dir\$project_name.UnitTests.dll"
	$output_unitTests_xml = "$build_reports_dir\UnitTestResults.xml"
	$output_coverage_xml = "$build_reports_dir\NCover.xml"
	$output_coverage_log = "$build_reports_dir\NCover.log"
	$output_coverageExplorer_xml = "$build_reports_dir\NCoverExplorer.xml"
	$output_coverageExplorer_html = "$build_reports_dir\NCover.html"
}
 
properties { # Skip coverage attributes
	$skipCoverage_general = "Testing.SkipTestCoverageAttribute"
}
 
task default -depends unit_test_coverage
 
task clean {
	$transient_folders | ForEach-Object { delete_directory $_ }
	$transient_folders | ForEach-Object { create_directory $_ }
}
 
task compile -depends clean {
	exec { msbuild $solution_file /p:Configuration=$build_config /p:OutDir=""$build_output_dir\\"" /consoleloggerparameters:ErrorsOnly }
}
 
task unit_test_coverage -depends compile {
	exec { & $tools_coverage $tools_nunit $output_unitTests_dll /nologo /xml=$output_unitTests_xml //reg //ea $skipCoverage_general //l $output_coverage_log //x "$output_coverage_xml" //a $project_name }
	exec { & $tools_coverageExplorer $output_coverage_xml /xml:$output_coverageExplorer_xml /html:$output_coverageExplorer_html /project:$project_name /report:ModuleClassFunctionSummary /failMinimum }
}

As the second line alludes to, you can break functions out into separate files and include them back into the main one. Here’s functions_general.ps1:

1
2
3
4
5
6
7
8
9

function delete_directory($directory_name)
{
	Remove-Item -Force -Recurse $directory_name -ErrorAction SilentlyContinue
}
 
function create_directory($directory_name)
{
	New-Item $directory_name -ItemType Directory | Out-Null
}

This script will build our project and run the unit tests, producing a coverage report we can display later inside Team City. Much of this maps loosely one to one against the NAnt version discussed in my past series, and there’s plenty of articles/posts online explaining this stuff in much more detail than I can here. Note that all the pieces that can “fail” the script are wrapped in exec, which will execute the code block (i.e. lambda/anonymous delegate) and basically alert the build server if it fails. Not too difficult, at least for now

As for getting this to work with Team City, if you specify the runner as a command line and point it at a batch file with these contents:

1
2
3

@echo off
cls
powershell -Command "& { Set-ExecutionPolicy Unrestricted; Import-Module .\build\tools\psake\psake.psm1; $psake.use_exit_on_error = $true; Invoke-psake '.\build\build.ps1' %*; Remove-Module psake}"

You’ll be golden. This batch allows the build server to run the script (perhaps setting unrestricted execution isn’t the smartest from a security standpoint, but oh well), sets up the psake environment, tells psake to raise its warnings in a way that TeamCity can pick up on, executes your build script, and tears down the psake environment. Looks a little complicated, but it’s just a bunch of smaller commands strung together on one line, and you shouldn’t have to look at it again.

I’ll walk you through doing this, assuming you don’t already have an SSH key or Github account (if you do, though, it’s no biggie, just make sure to back everything up and swap out a few obvious steps below).

1. Sign up with Github.
2. Download & install msysgit (chose to use the OpenSSH instead of Tortoise/Putty’s PLink when prompted).
3. Open a Git Bash prompt (an icon is placed in the Start menu during msysgit’s installation).
4. Create your SSH key pairs, doing the following steps once for each email/account (internal work & external public ones, for instance):
   1. ssh-keygen -t rsa -C "public_or_private@email.com"
   2. When it asks for the file to save to, specify the same folder it’s suggesting for the default one (i.e. /c/Users/dmozingo/.ssh/) but name the file something different, based on whether it’s for the public or private key (maybe something like id_rsa_github and id_rsa_work).
   3. Enter a passphrase. I usually leave it blank as other guides suggest, trusting (perhaps mistakingly?) Window’s folder security to keep it safe for me.
5. Navigate to the folder where you just created your SSH key pairs, and create a file named config.
6. Open the file in notepad and enter the following:

   Host github.com
   	HostName github.com
   	User git
   	PreferredAuthentications publickey
   	IdentityFile /Users/dmozingo/.ssh/id_rsa_github
   
   Host work
   	HostName workGitServername
   	User dmozingo
   	IdentityFile /Users/dmozingo/.ssh/id_rsa_work
   

   You’ll have to do a few substitutions in the file, mainly for the work HostName and both section’s IdentityFile’s, if they’re different for your setup. The first line of each section specified the name you’ll use in “addressing” your Git commands later. By keeping the first one github.com, you won’t have to change anything when you follow along with other guides online.
7. Now give GitHub the contents of your public/GitHub SSH key file (the id_rsa_github.pub from my example). You can do this on your account settings page.
8. Still at the Git Bash prompt, enter ssh-agent.exe bash to start the key manager. You’ll have to do this each time you use Git, unless someone (please?) can tell me a better way.
9. Enter ssh-add.exe ~/.ssh/id_rsa_github, where the tilday (~) represents your home directory (C:\Users\username for Vista/7, C:\Documents and Settings\username for XP). This should point to the public SSH key file you made earlier. You’ll also have to do this each tiem you use Git, again, unless someone can set me straight here.

That should be it! Test it out by entering ssh git@github.com. You should see something like this:

So while it’s definitely harder than not having to juggling multiple accounts, it’s not as bad as it sounds. Know a better way to do this? Please let me know!

By using a shortened variable or method name, you’re forcing some other developer in the future (who often ends up being yourself) to mentally substitute that shortened version in their head each time they see it while reading through your code. Lets face it, our code is usually hard enough to understand long after we’ve written it just on its own, so strive to do everything possible to more quickly and easily figure it out in the future. Those small substation times accumulate pretty quick when you’re trying to find a bug in foreign code.

Queue the contrived example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

public int AddEmp(string fname, string lname, decimal rate, Dept dept)
{
	var emp = EmpFact.CreateEmp(fname, lname, rate, dept);
 
	this.Employess.Add(emp);
 
	var x = 0;
 
	foreach(var emp in this.Employees)
	{
		x++;
	}
 
	return x;
}

Yea yea, like I said, contrived. Anyway, while you can probably tell somewhat easily what’s going on there, you can see there’s a lot of common and not so common abbreviations and shortened names being used. Dept? x? What they hell do they do? Lets try this again without being quite so lazy:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

public int AddEmployee(string firstName, string lastName, decimal payRate, Department department)
{
	var newEmployee = EmployeeFactory.CreateEmployee(firstName, lastName, payRate, department);
 
	this.Employess.Add(newEmployee);
 
	var newEmployeeCount = 0;
 
	foreach(var employee in this.Employees)
	{
		newEmployeeCount++;
	}
 
	return newEmployeeCount;
}

A bit better, I’d say. On your first read through this code it’s easier to see what’s going on and what each piece plays in the puzzle. You don’t have to stop for a split second to think “first name” when you see “fname”. You just read “first name”.

I know a lot of people scoff at longer names when they first see them (like FindAllCustomersInStateNotUsingDiscountWhenAvailable), but that’s cool. It is weird at first, but you get used to it. Even more foreign to most developers is using underlines for spacing: Find_all_customers_in_state_not_using_discount_when_available. I personally find that version even more readable as you don’t have to mentally parse the words, but it’s a hard pill for a lot of developers to swallow.

Regardless of how you do it, the next time you find yourself using a quick abbreviation or some meaningless variable/method name, please do your future self and other developers a favor by putting some meaning into it.

Turns out (surprise surprise!) that getting your rendered HTML from the Web Forms view engine that’s used by default in ASP.NET MVC isn’t so, um, easy. It likes its HttpContext with a side of HttpSession, and that’s just the appetizer. Kind of hard to get that to it in-memory without firing up a whole other server instance. Thankfully, it turns out our good friend Spark makes rendering a view to an HTML string in-memory incredibly easy.

How? Glad you asked:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

public static string RenderViewToHtml<VIEW_MODEL>(string viewPathAndName, VIEW_MODEL viewModel) where VIEW_MODEL : class
{
	var templatesLocation = new FileSystemViewFolder(HttpContext.Current.Server.MapPath("~/Views"));
	var viewEngine = new SparkViewEngine(BuildSparkSettings()) { ViewFolder = templatesLocation };
	var descriptor = new SparkViewDescriptor().AddTemplate(viewPathAndName);
 
	var view = (SparkView<VIEW_MODEL>)viewEngine.CreateInstance(descriptor);
	view.ViewData = new ViewDataDictionary<VIEW_MODEL>(viewModel);
 
	string html;
 
	using (var writer = new StringWriter())
	{
		view.RenderView(writer);
		html = writer.ToString();
	}
 
	return html;
}
 
public static SparkSettings BuildSparkSettings()
{
	return new SparkSettings()
		.AddNamespace("System.Linq")
		.AddNamespace("System.Web.Mvc")
		.AddNamespace("Microsoft.Web.Mvc")
		.SetPageBaseType(typeof(SparkView))
		.SetDebug(false);
}

Simply pass in a path to your view (minus the /View part) along with a view model and you’ll get back a string full of rendered HTML goodness. The BuildSparkSettings() method can shared with the application startup code where you create and add Spark as an ASP.NET MVC view engine. Here’s a sample call:

It’s worth noting that Spark and WebForms views can happily live side-by-side in a single project, too. We use this for only a hand full of pages and the rest are still using the WebForms view engine. Plus, converting them to Spark was as simple as renaming the file and adding a view model declaration at the top of the page (along the lines of <viewdata model="OurNeatViewModel" />). Granted these pages aren’t really leveraging the power and beauty of Spark, but they still run and with virtually no modifications.

Will we be converting all of our views to Spark and using some of it’s neat-o features and conventions? Probably not any time soon. While lots of folks are apparently feeling lots of pain with Web Forms views, we’re not (well, other than this whole in-memory rendered affair anyway). So there really isn’t much gain for us from switching over. I also really don’t like the non-strongly-typedness of their views, which already bit me a few times just on the hand full of views we’re using it for. Perhaps that might get fixed or ReSharper will step up with support for it.

Spark does have a lot of neat features though. It’s ability to easily render a full view to an HTML string in-memory was just the first thing we needed from it. I’m sure there’ll be more in the future.

My home-ran Linux server crashed shortly after the first of the year. I’ve gotten really good up time with it since I started using it 6 years ago, with only a power supply dieing on me once, and other than that having gone years at a time without having to do a single thing - even rebooting. Well, I’m thinking the motherboard gave out this time, and I really don’t feel like messing with the server any more between software updates and hardware issues (plus it was hosted in my company’s data center, and with a few of the ideas I’m hoping to bring to fruition this year, I don’t want to overstay my welcome there!).

So I moved to an actual hosted solution with Site5. I never realized it’d be so hard to find a freakin’ provider! I understand it’s probably the nature of the beast, but it seems like there’s no single provider out there that damn near everyone just loves, even as you move up the price scale. For every story about someone being with a host for years without a single problem, there’s one where they guy’s site was down every other day and he lost half of his data in a crash. Eek! I’ve have heard good things about Site5’s Ruby on Rails hosting and their uptime in general, however, plus they provide SVN & Git on all their servers so I don’t have to worry about hosting that separately with GitHub or Unfuddle, so I took the plunge for a year to try them out. Pretty good so far, though there were a few hiccups such as having to move my DNS hosting to them and at least one server outage. Guess I’ll see how it goes.

Anyway, that’s why the site was done for two weeks or so. Hopefully it shant happen again any time soon.

Books

1. Code Complete - Steve McConnell
2. Patterns of Enterprise Application Architecture - Martin Fowler
3. Applying Domain-Driven Design and Patterns - Jimmy Nilsson
4. Working Effectively With Legacy Code - Michael Feathers

Tools/Techniques/Processes @ Work

• Move from SVN to Git (and learn more about Git in the process).
• Move from CC.NET to Team City for our build server.
• Build a more robust build script and management process - including production deployment and database migration scenarios.

Involvement

• Develop an idea I was given for an open source project and get it live to see what happens.
• At least 24 blog posts (I’m not going to say 2 per month as I’m getting married this summer and I’m certain I won’t be able to maintain a schedule around it).
• At least 3 feature/patch submissions to open source projects.

Coding

• Get a version 1 out there on at least 1 of the 3 product ideas I have floating around.
• Keep working on a good working knowledge of Ruby & Ruby on Rails (and use it to build the product mentioned above).

Pretty similar to last years goals overall, actually. I’ll be updating my progress every 3 months instead of 2 this year though.

Set any goals yourself this year?

Books

1. Code Complete - Steve McConnell (yep, I’ve never actually read it)    No progress.
2. Patterns of Enterprise Application Architecture - Martin Fowler    No progress.
3. Domain Driven Design - Erick Evans    Done.
4. Working Effectively With Legacy Code - Michael Feathers    No progress.

Tools/Techniques/Processes @ Work

• NHibernate and all its trimmings (FluentNHibernate, LINQ to NHibernate, etc), which I’ll need on a project here real soon.  Done.
• Actually move from CC.NET to Team City (last attempt didn’t go so well).  No progress.
• Build a more robust build script and management process - including production deployment scenarios.   No progress.
• Messaging framework, either MassTransit, NServiceBus, or Ayende’s new Rhino Service Bus if he’s able to release it in time for our current project.  Didn’t need it, so no progress.

Involvement

• We have weekly meetings to catch everyone up on what we’re doing, but I want to present on an actual topic during at least 2 of these - and present in a way where the other development teams will see the use in picking up the presented tool/technique.    Meetings still halted - no progress.
• Have at least one meeting of the CantonALT.NET group and see if it can ever get up on its feet.   No progress, and more than likely dead in the water
• The two blog posts per month target John put out there seems doable, so I’ll borrow it :)    Spot on, but no posts during October or November. I’ll consider this goal missed, then.
• At least 3 feature/patch submissions to open source projects.  Done.

Productivity

• Trim RSS feed size by 1/3 (presently at 127, so trim it to at least 85) and cut time viewing it by half. I’ve gotten much better this past year at cutting through the useless stuff, but there’s still a lot there and it sucks up too much of my time.  Done.

So, overall I completed 4 of my 13 goals - 31%. Ouch. To be fair, 2 of the goals were out of my hands (didn’t need a messaging framework at work yet and didn’t want to think up some rinky-dink example project to try it on, and our weekly meetings were cancelled for me to present - though I could have found another venue to present). I was also pretty close on the blog posting goal, only missing a few because I ran short on ideas for a couple of months there.

Ah well, at least I gave them all a shot and completed at least one from each category. I also knocked off a lot of my personal goals for the year, so they sort of balanced out. I’ll post my code related goals for the upcoming year later this week.

How’d everyone else do? Have any new ones for this year?

What is it?

Many objects have an outside dependency of some sort. Instead of creating the dependency inside your class (by doing something like myDependency = new Dependency()), you want these dependencies to be “injected” in, usually by the constructor:

1
2
3
4
5
6
7
8
9

public class OrderProcessingService
{
	private readonly IRepository _repository;
 
	public OrderProcessingService(IRepository repository)
	{
		_repository = repository;
	}
}

That’s it. Seriously. It’s not hard to grasp, and you’re probably already doing it, but the trick for me was figuring out how to actually go about using this in any sort of sane and recommended way, as you’ll notice the requirement is now on the caller to provide an instance of IRepository. If you want more details on this pattern, there’s plenty out there.

Why should I bother using it?

1. It takes handling the dependency’s life cycle out of your hands. Perhaps you want your database access class to stick around for a whole web request, another object to be a singleton, and another to be per thread when used in a Windows app, but per request in a Web app? Using a proper DI framework/container, you don’t have to worry about writing anything to support that, and changing the lifespan of a given object is a one line (and usually even enumeration value) change.
2. It loosens up your code. You’re no longer “newing” up your data access or web service classes right in the middle of your operation. Swapping out implementations of, say, an interface, is a simple operation that’s located in one place. Just stick the dependency in your constructor, and you’re good to go. I’ve actually used this in quite a few places beyond the academic and largely unused-in-the-real-world “switching from Ms SQL to Oracle” examples, too.
3. Greatly eases and simplifies unit testing. In many cases, using dependency injection is the only way to unit test portions of your code base (unless you use a certain tool to do it for you). By taking your dependencies in your constructor, you’re giving your unit tests a seam to inject fake implementation of these dependencies. This lets you skip actually hitting the database, web service, hard drive, or anything else that would kill the running time of a unit test or be almost impossible to setup and control in a repeatable manner.

How can I use it?

Ah, now for the juicy part I know you’re all dying to hear: how the hell to actually use the pattern in conjunction with one of the tools I mentioned at the beginning of the post. Before giving away the answer, let’s quickly go over the three primary ways to use a DI container in your app:

1. Service locator: this pattern is generally considered a no-no, as it still burys your dependencies deep inside your code. Sure, you can swap them out when needed for unit testing, but they’re still very opaque and will almost certainly get very hard to work with, very fast:
   
   

   1 2 3 4 5 6

   public void ProcessOrder() { var repository = IoC.Resolve<IRepository>();   // Do stuff with repository. }

   In the above example, IoC.Resolve is a simple static method that delegates to whatever DI framework you’re using. Callers won’t know about this dependency, though, and without fully boot strapping your framework in your unit test (icky) or injecting a fake into your container, the call will either throw or return null, neither of which you want to be checking for everywhere.
   
   
2. Poor-man’s dependency injection: This is a slight twist on normal constructor DI. You have one empty constructor for most of the program to use, which delegates to a “loaded” constructor that unit tests use. While making the dependencies clear, this removes lifetime management from the container’s hands, and also gets ugly when you start changing dependencies around. This is usually used in conjunction with the service locator pattern above:
   
   

   1 2 3 4 5 6 7 8 9 10 11 12 13

   public class OrderProcessingService { private readonly IRepository _repository;   public OrderProcessingService() : this(IoC.Resolve<IRepository>()) { }   public OrderProcessingService(IRepository repository) { _repository = repository; } }

3. True dependency injection: Classes generally have only one constructor which takes in all the required dependencies (see the first code snippet at the top of the post).

After enough playing around, reading, and looking at other open source projects, though, it finally clicked: only call Resolve at the furthest edges of your application, and as few times as possible. So what does that mean and where should you be calling it in your app? Well… it depends.

Wait, isn’t that just another cop-out?

Well, yes and no. Yes in the fact that I’m not giving a solid answer, no in the sense that it really does depend on your application: what frameworks you’re using, how you have its architecture setup, etc.

Just so you can’t say I’m not providing anything solid, here’s how I’m using it in our current app:

1. We’re using ASP.NET MVC & StructureMap, so we’re using a custom controller factory that creates controllers from the container. This means we can create an EmployeeService, extract an interface for it named IEmployeeService, put it as a requirement in the controller’s constructor, and it’s satisfied magically at run time. Even cooler, everything down the object graph from EmployeeService (say, an EmployeeRepository, or LoggingService, or EmailService, or anything else you need) gets their dependencies all satisfied automagically, too. We can stick a constructor argument in virtually anywhere and it’s taken care of for us, without giving it a second thought! Each web request, this all gets built out.
2. We have a basic home brewed scheduled task framework that, given the name of a task you want to run (say /run Emailer runs the EmailerTask), instantiates the requested task class, and runs it. We use the container at the point of instantiation, effectively treating each “task” class as a controller from above, filling all the dependencies it needs down the object graph.
3. We also fire off the scheduled task app by doing an IoC.Resolve<IApplication>().Run() in the console app’s Main method, giving the app everything it needs.

Now, what if you’re using WebForms? Well, you’re not *completely* out of luck. It’s a pain, to be sure, but still doable.

Wrapping up

I hope this helped cleared up dependency injection for you a bit. Just remember to use the actual Resolve call of your container in as few places as possible in your application, and only on the “outside edges” of the app. Look at where you do all your main object creation (your web forms, Windows forms, controllers, WCF factories, Silverlight pages, etc). Stick the call in there, and forget about it.

Good luck.

Disclaimer: My team and I have only been doing this for a short time, so please, for the love of all that is holy, don’t take my word as gospel on any of this. We’re learning more about this each day, but we’re still far from proficient or experienced. I’m just putting what we do and what we’ve learned out there to possibly help others, as I know we would have loved to hear this when we started. If you blow up your repository and lose all your code, it’s not my fault.

That said, lets discuss what Branch-Per-Feature is and how it typically works. I won’t get into much detail on why you should do it or what it is here, as Derick Bailey has an excellent, though unfortunately unfinished at the moment, series of posts on the subject and they’re a must read to get a solid background on this. In a nut shell, though, Branch-Per-Feature is basically what the name implies - you create a branch in your source control system for each “feature” you work on (where the “feature” can be defined as big or as small as you want - we’ll skip doing this for typos and the like). You can then work on that feature in isolation in your own branch, committing your changes as often as you like and not screwing up your other teammates or being affected by them, until you’re all finished, at which point you merge the completed feature back into the trunk. Using this methodology, the trunk should always be kept in a “shippable” state.

Sounds easy enough, right? As is often the case, however, the devil is in the details. I’m sure the first thing that jumps out at you in reading about this is “how the hell does this work with multiple developers?”. Well, the theory goes that as you’re working on your feature branch, you continuously merge changes from the trunk (i.e. features other developer’s have finished) into your branch. This means instead of merging after 2 weeks of work and finding a crap load of conflicts, you have a few here and a few there. In practice it generally works out that way, too, unless you or a team mate goes on a refactoring rampage and you need to merge those changes in (I’m usually guilty of this myself - sorry guys!). Following SRP and the small class sizes that result from it helps in the fact that multiple people usually aren’t working in the same class, too.

Simple scenario

I’ll walk through the steps of a simplified “feature” branch from start to finish. Simplified here means you’re either working by yourself, or you know nobody else has changed the trunk while you’re working on your feature. As the title of this post alludes to, I’ll be showing this using Subversion coupled with TortoiseSVN, so I’m not terribly sure how it’ll work with similar source control systems. Also, while all the tools and practices that I’m going to show here do help with merge problems and the like, they’re not a substitute for using actual communication on your team inorder to avoid problems. Sorry, but you just can’t get away from talking to people

Note: all of this is shown with a version of Subversion & TortoiseSVN > 1.6, as many of these features have only been included since then. Make sure the server, client, and your repository are upgraded to at least this version (especially check the repository, which needs upgraded separate from the server, which we learned the hard way). Ask your admin if you’re unsure about any of this.

Now, say we have a repository named BranchPerFeature with the standard /trunk, /branches, and /tags folders. It has a simple console app that displays a welcome message. Call me weird, but I’ve never liked the SVN switch command, so I just setup a local directory structure similar to the repository’s:

We’ll start by creating a branch for our new feature. Right-click your checked out trunk folder, then select TortoiseSVN, then Branch/Tag. In the To URL field, we’ll enter a path in the branches folder in the repository, usually named after the feature we’re working on. In this case we’ll create a branch in branches/AddUserInput (we’re adding a Console.ReadLine() in this feature - exciting, huh?):

Now you can checkout that new branch in your local branches folder and start working on the feature, committing as often as you’d like knowing you’re not affecting anyone else. When you’re all done and everything is committed to it, we’ll merge it back into the local copy of your trunk. Go to where you have the trunk checked out, right-click and select TortoiseSVN, then Merge. Of the three options you’re presented with, select the second, Reintegrate a branch:

We’re merging from our branch, so enter its repository URL in the From URL and hit next:

Hit Merge on the final screen (or use the Test Merge button to do a dry-run that won’t affect anything). Remember, at this point all changes made from your branch, and applied to the trunk, are only local. Now open the updated trunk, run all your unit tests and whatnot, then commit these changes to the repository:

Congrats! Your first feature branch is finished and merged back into the trunk, hopefully with no problems. One major caveat of this procedure is you must not use your branch again after it’s merged back into the trunk. Why? Well, Subversion keeps some properties set on all your files/folders so it knows what revisions have been merged back into them, and continuing to work on your now stale branch and trying to merge it back into the trunk again at a latter point would be bad ju-ju. To make sure nobody accidentally uses your branch, be sure to “delete” it from your repository (don’t worry, the history is still available, just not readily available). To delete the branch, right-click on your checked out trunk folder, select TortoiseSVN, then Repo-browser. Navigate to your branches folder in the left pane, then right-click and delete your old branch:

A bit more complicated scenario

So you created your branch and you’re happily committing away when you see someone else committed to the trunk. Uh oh. Fortunately, it’s really not a big deal. We’ll just merge the new revisions from the trunk into our branch every now and then to keep it “current” with the trunk. Then when you’re done with your branch and go to merge it back into the trunk, it should theoretically merge without problems, as it’s the same as the trunk except for the changes you’ve made.

To show this, we’ll create a new branch to add a prime number calculator to our app. Same steps as above. After we’re working on the branch, though, we’ll commit a change to the trunk to simulate it being a co-worker’s change (it can be anything, even a conflicting change if you want). Now it’s time to update you branch!

First, check-in any changes you’ve made on the branch (this allows you to roll back the coming updates if they blow up, among other things). Then right-click on your checked out branch folder and select TortoiseSVN, then Merge. Choose the first option this time, Merge a range of revisions:

Make sure the trunk is specified in the URL to merge from field on the next screen. Leave the Revision range to merge field blank, as Subversion tracks which revisions it already merged in automatically and won’t try to re-merge them (which is new in version 1.6 - for older versions you’ll have to track this and specify revision ranges by hand, and trust me, it gets messy real quick):

If you hit the Show Log button on this screen, it should show revisions that have already been merged in gray:

As a quick side note, when everything is done, you can do a diff on the files and see how Subversion tracks previously merged revisions on each file & folder:

After hitting next, you can hit either Merge or Test Merge (just like before), and make sure everything gets updated. Deal with any file or tree conflicts here, and run all your unit tests to make sure these new changes are still hunky-dory with your stuff. Then simply commit these new updates to your branch:

Keep up on these trunk updates while you’re working on your feature, and when you’re done and it’s time to merge back into the trunk, you shouldn’t have any (or at least not many!) issues or conflicts with it.

Monitoring the trunk

How can you know when changes are made to the trunk? Well, you can have everyone yell out when they commit to the trunk if you work close enough, you can email everyone, or you can get a tool to monitor the repository for you, such as SVN-Monitor which is quite awesome and totally free.

I set this up to monitor our trunk so I know when changes are made, with both a nice pop-up balloon and an email. Here’s a view of this sample’s trunk:

Complex scenarios

You’re bound to run into issues now and again with this workflow, especially on larger teams, having a more complicated branching setup, or if you’re doing a lot of file shuffling in the trunk or your branch (as its been my experience that, in general, SVN doesn’t deal well with file moves/renames beyond the simple cases). I’m also working on a 3 person team, so I can’t speak as to how well this scales up to a 15 person team size.

I’m not pretending to cover every scenario or issue you’ll run into in this post, either, so accept that fact that you might, and probably will, have to either Google around for an answer to some weird error and drop down to the command line to fix something. You might as well know that going in.

Issues?

The biggest issue I have with this workflow so far is the time taken to create a new branch, mostly comprised of the time spent checking-out and updating R#:

• Check-out time: as I mentioned, I don’t like the switch command (though it would probably solve this issue). We’re work on a large, and rapidly expanding, code base with over two dozen dependencies and lots of code files. It simply takes a while to check out a new branch (ok, in reality it’s only a few minutes, but still annoying).
• Updating R#: I love the solution wide analysis R# offers, but it takes a while to scan everything when you open a newly created & checked out branch. This is on a quad-core machine with 15k RPM drives, too.

These issues, while not show stoppers by any means, are still annoying to me none-the-less, and I thought I’d mention it.

Wrapping up

So there you go. Common usage scenarios when using a branch-per-feature workflow with Subversion. Not too complicated. As I noted in the begining, we’ve been doing this for a short while now and it’s working quite nice, as before we’d just make one branch for each iteration, all work in that, and merge with the trunk when done. That meant if one of us was making breaking changes, we’d simply not commit until we were all done. That’s pretty risky. What happens if our machine crashes after 4 days of work, or we wanted a file back from a few days ago? Not cool.

It’s worth noting that, from what I understand, Git’s workflow follows this pattern by default. I’m planning to dive into that soon.

If I messed anything up in here, or you know a better way of doing it, please let me know!