Friday, November 27, 2009

Four Bits Worth of Dev Advice: Last Half a Bit

This the 5th and final post in my series about my 16 pieces of developer advice. In the previous post I listed the 16 pieces in headline form ([1]), and briefly explained the first 12 pieces ([2], [3], [4]). In this post I go through the last four pieces. Enjoy!

1100: Write change friendly code
This piece of advice is about a mind set: Keep in mind that the code your writing will most likely be changed a lot of times in the future. Therefore you need to write code that can be changed without too much pain. This mind set leads to a lot of the common coding best practices like using symbolic constant, like avoid unnecessary dependencies, like keeping functions short and the list goes on and on. These things brings readability to the code, and they enable changing the code later on. On the other hand you should (of course) avoid over-designing software, so this nugget is really mainly about the small code level things. And those small code level things make a huge difference when it comes to the modifiability of software.

1101: Dry
Don't repeat yourself. Or DRY. This piece of advice has been re-iterated so much, that I will leave at a reference for you to follow, the C2 wiki entry on DRY.

1110: Don’t stay stuck
You sometimes get stuck when coding, in fact some days coding feels like this:

Getting into situation where you are stuck and can't see what the next step is, is normal and something you need to accept as part what it's like to write code. The important part is what you do about it. Some developers start thrashing; they run around in circles without really getting anywhere. Others start surfing for cartoons (or ... well, you get the idea). That doesn't help. To get out the situation your stuck in you probably need help - I know, I usually do - so seek help. Ask a team mate to pair with you. Ask your project manager for that tool you need. Ask a senior colleague to take a look at your problem. Read up on the relevant literature. Just don't stay stuck.

1111: Be curious
The final piece of advice on the list is simply to be curious in your work. And use that curiosity to gain technical insight. For instance ask yourself how the frameworks or libraries you use are implemented. Maybe read some of the code, step through it in a debugger, or read the documentation (yes, it said read the documentation :-) ). Or take a look at the code your compile generates, be assembler, bytecode, MSIL or something else. That generated code can tell you a lot about how the platform and language you're in actually works. Just try to stay curious about how things actually works, and spend a bit of time and then satisfying that curiosity.


So that was my list of 16 pieces of developer advice. I had fun compiling the list. I started out with a much longer list, but it was fun to boil it down to 16. What do you think is missing from the list, and do you think should be taken out?

Friday, November 13, 2009

Four Bits Worth of Dev Advice: Half a Bit More

This is the fourth post in my series of four bits worth of dev advice the first three ([1], [2], [3]) covered the sixteen pieces of advice in headline form and the first eight pieces in a bit more detail. This post goes through another four pieces of advice.

1000: Use symmetric interfaces
When designing an interface we have to decide which methods the interface contains. If you know exactly how the interface will be used - e.g. you're the guy developing the code that uses the interface - deciding what's in an what's out of the interface is pretty straight forward. If, on the other hand the interface will be used in unknown ways - e.g. you're developing a library that others will use - the decisions are harder. In the later case symmetry can be an excellent guide: If an interface has method A that has a logical inverse operation B, the interface should probably have B method. For instance, consider this code from the Rotor project:


class CClassFactory :  public IClassFactory
{
CClassFactory() { }

public:
CClassFactory(const COCLASS_REGISTER *pCoClass) : m_cRef(1),m_pCoClass(pCoClass)
{ }

// snip

virtual HRESULT STDMETHODCALLTYPE CreateInstance(IUnknown *pUnkOuter, REFIID riid,
void **ppvObject);

// snip

private:
LONG m_cRef;
const COCLASS_REGISTER *m_pCoClass;
};


This is a typical factory: It can instantiate a certain type of object through the CreateInstance method. Since this is C++ those objects have to be deleted (or at least logically freed, if some sort of pooling is in place) at some stage. But the factory interface does not help us there, so we can only guess how deletion is supposed to be done. This is a case where introducing the symmetric method DestroyInstance might make sense. That makes the code look like this:


class CClassFactory :  public IClassFactory
{
CClassFactory() { }

public:
CClassFactory(const COCLASS_REGISTER *pCoClass) : m_cRef(1),m_pCoClass(pCoClass)
{ }

// snip

virtual HRESULT STDMETHODCALLTYPE CreateInstance(IUnknown *pUnkOuter, REFIID riid,
void **ppvObject);

virtual HRESULT STDMETHODCALLTYPE DestroyInstance(void *ppvObject);

private:
LONG m_cRef;
const COCLASS_REGISTER *m_pCoClass;
};

Adding symmetric operations to interfaces is not a fast rule. That DestroyInstance method might not be necesarry in the case above - I haven't diged deeply into the Rotor code, so I don't know. But if you're in doubt, and including the symmetric operation(s) doesn't seem un-economic, make the interface symmetric.

1001: Use one abstraction level per method
This a classic from Martin Fowlers Refactoring book: In order to write nice readable methods use only one level of abstraction within any given method. If a method contains some code that operates on a higher level of abstraction, and some code that operates on a lower level of abstraction, the lower level code should be extracted to a separate method.
Operating on only one level of abstraction in each method allows the reader to stay on that level of abstraction when reading the method, which is a lot easier than mentally jumping between levels of abstraction. Furthermore the reader knows that he is going down to a lower level of abstraction when going into the implementation of a method, B, which called from another method, A.
To illustrate take a look at this lovely piece of (in-production) Java code:


private void init() {
try {
server = new ServerSocket(Integer.parseInt(PersistentData.getStringValue(PersistentData.UDP_PORT_MLPI,
PersistentData.UDP_PORT_MLPI_DEFAULT_VALUE)));

javavendor = System.getProperty("java.vendor");
System.out.println("Java vendor: " + javavendor);
if (javavendor.startsWith("Sun ")) {
m_DatagramThread = new
DnDatagramThread("localhost",Integer.parseInt(PersistentData.getStringValue(PersistentData.UDP_PORT_WCTRL,
PersistentData.UDP_PORT_WCTRL_DEFAULT_VALUE)));
}
//snip
} catch (java.net.BindException e) {
System.err.println("A previous instance is already running...." + "\nCannot run application: " + e.getMessage() + "\n" + e);
System.exit(1);
} catch (final java.io.IOException e) { // an unexpected exception occurred
System.err.println("Cannot run application: " + e.getMessage() + "\n" + e);
System.exit(1);
}

m_properties = new HashMap();
m_splashScreen = new SplashScreen();
ErrorDialog.instance().setInitialWindow(m_splashScreen);
ErrorDialogCheck.instance().setInitialWindow(m_splashScreen);

progress(5);
setupDebug();
progress(10);
}
This code opens a socket - one level of abstration - then creates and sends a datagram over that socket - another, lower, level of abstraction - and goes on to display a splash screen - a third, higher level of abstraction. Having those three levels of abstraction means that the reader has to think about sockets, protocol specifics and GUI simultaneously to grasp what is going on in the code. That's not separation of concerns. That's spaghetti.

1010: Grow GUTs
Grow some GUTs while developing software. That is grow some Good Unit Tests. Good unit tests express and test the intended functionality of the code under test. It covers not only the different paths through the code, but all the requirements that the code under test is supposed to fulfill.
Most of the unit tests I see revolve around the implementation details of the code under test rather than the actual functionality. Lots of test suites are build by creating one test method per public method in the code under test. Each of these test methods try to cover one method from the code under test. This usually means that most of the tests only check very superficial things, and then one or two of the test methods test an awful lot of things all at once because try to cover the one or two central public method of the code under test. These large test methods become unwieldy, while still not covering the entire functionality of the code under test. Basically the public interface of the code under test is bad unit test template - a BUTT. And who wouldn't rather grow their GUTs than their BUTT?
For a thorough write-up on good unit tests I recommend Kevlin Henneys StickyMinds series ([1], [2]) on the subject.


1011: Prefer use over reuse
Writing re-usable software is something lots of developers want to do. Writing re-usable software is also really hard. In fact, writing usable is hard. And if software isn't even used it certainly won't be reused.
Moreover aiming for reuse in the first iteration over a software design tends to make the design bloated and unclear (i.e. un-economic), because the requirements to the software are unclear, and because there are multiple scenarios in play that the design tries to accommodate. That sort of bloated software will just end up sitting unused on your hard drive. To counter that, focus on one scenario that you're sure of. Prefer to make something that is used in just that one scenario. Then go on to build something that is used in one other scenario. Then go on to build something that is used in a third scenario. Only then, after a number of instances of use, think about reuse.

That's it for now.

Thursday, September 24, 2009

Four Bits of Advice: Another Bit

This is the third post in a short series of post about developper adivce ([1], [2], [4]). The first one listed 16 pieces of advices in the form of headlines. The second post briefly explained the first 4, and this post is about the next 4:


0100: Consider infrastructure orientation
Where should infrastructure code go? Well, what is infrastructure code? It's code enabling domain objects to be used by the infrastructure parts of an application, like data persistence parts, the serialization parts, or the remoting parts. Often such code is added to domain objects in a vertical manner via inheritance, resulting in something along the lines of:















This works fine in a lot of cases, but there is the alternative of having the domain objects contain references to infrastructure objects, and letting them delegate to the infrastructure code when needed. That alternative results in a horizontal arrangement of domain and infrastructure code, which looks something like this:


The point is not that orienting infrastructure code horizontally is better than vertically. The point is that it is worth evaluating both option when designing a piece of software.

0101: Use role based interfaces
Interfaces, as in C# or Java interfaces, should define a single role an object can play. An object, on the other hand, can play several roles, and therefore it is perfectly all right for a class to implement several interfaces. This opposes a style of programming often seen in both C# and Java: Given a class called Foo, there is an interface called IFoo. The only class that implements IFoo is Foo, and all the public methods of Foo are implemtations of IFoo methods. An interface like IFoo does not add much value: It does not express or define anything that the public interface of Foo does not already express and define. The only thing IFoo adds is a test seam. Granted test seams are important and valuable, the same seam and more seams are available if Foo implements a number interfaces each defining a role. These roles make sense in terms of the application and its domain. Therefore they make the software easier to read, and with any luck more flexible.
For more on this I recommend Martin Fowlers post about role interfaces.

0110: Be economic
Do waste resources unnecessarily. Specifically: Do not make interfaces larger than they need to be. Do not add extra features to interfaces "just in case", or "because I can". The same goes for larger designs. Adding that extra stuff is wasteful, because you have to spend time writing it, because other programmers have to spend time reading and understanding it, and because it needs to be tested. Furthermore the shorter more concise implementation is usually the more elegant.
For more on this read through Kevlin Henneys slides on economy and elegance.

0111: Prefer code over comments
Comments can and do lie. Comments become obsolete and out of date. Comments are overlooked by programmers. By contrast, code is actually read by programmers, code is and stays current, and code with good naming can often express what would otherwise have been written in comments.
Thats it for now.

Sunday, September 20, 2009

97 Things Every Programmer Should Know

I have contributed a piece to the 97 Things Every Programmer Should Know wiki, which is a wiki containing a long list of good advice for programmers. The plan is that the wiki will turn into a book, by the same name as the wiki. There are well over 100 pieces on the wiki by now, and it's well worth the read; there are a lot really good tidbits.
The piece I contributed is about preferring declarative code over imperative code. It's at http://programmer.97things.oreilly.com/wiki/index.php/Declarative_over_imperative, if you go read it I would appreciate your feedback.

Sunday, September 13, 2009

Build automation with psake

I finally got a chance to take a proper look at psake, a build tool using PowerShell for the build scripts. Below is a psake script I did for a propject. It can compile the code by using MSBuild, clean up binaries, run NUnit tests, measure test coverage, and show the coverage results in the NCover gui. To do so a few paths are setup in the propoerties section, and it is assumed that tests reside in projects with names that end with Test:
properties {
 $base_dir = Resolve-Path .
 $testAssemblies = (Get-ChildItem "$base_dir" -Recurse -Include *Test.dll -Name | Select-String "bin")
 $buildartifacts_dir = (Get-ChildItem "$base_dir\src\" -Recurse -Include bin)
 $src_dir = "$base_dir\src"
 $tools_dir = "$base_dir\tools"
 $nunit_dir = "$tools_dir\NUnit-2.5.2.9222\bin\net-2.0"
 $ncover_dir = "$tools_dir\ncover"
 $db_script_dir = "$src_dir\Database"
 
 $env:Path += ";$ncover_dir;$nunit_dir"
 
 $test_result_file_postfix=".test-result.xml"
}

task default -depends Compile

task Compile {
 exec msbuild "$src_dir\DummyNameToProtectTheInnocent.sln"
}

task Test -depends Compile {
 foreach($test_asm_name in $testAssemblies) {
  $file_name =  [System.IO.Path]::GetFileName($test_asm_name.ToString())
  exec nunit-console.exe $test_asm_name /nodots
 }
}

task Coverage -depends Compile {
 $old_dir = pwd

 foreach($test_asm_name in $testAssemblies) {
  $file_name =  [System.IO.Path]::GetFileName($test_asm_name.ToString())
  $working_dir = [System.IO.Path]::GetDirectoryName($test_asm_name.ToString())
  $out_file_name = "$base_dir\$file_name".ToString().Replace(".dll", "") + ".coverage.xml"
  
  cd $working_dir
  NCover.Console.exe nunit-console.exe $file_name /nodots //x $out_file_name
  cd $old_dir
 } 
}

task Coverage_Gui -depends Coverage {
 foreach($xml in (Get-ChildItem . -Name -Include *.coverage.xml)) {
  tools\ncoverexplorer\NCoverExplorer.exe $xml
 }
}


task SetupDB {
 ."$base_dir\execute-sqlfile.ps1"

 Execute-SqlFile "$db_script_dir\RestoreBaseLineDB.sql" ".\SQLExpress" "master"
 Execute-SqlFile "$db_script_dir\SQL_CreateLoginAndPermissions.sql" ".\SQLExpress" "ConnectPortal"
 Execute-SqlFile "$db_script_dir\AddCompanyIDsToModul.sql" ".\SQLExpress" "ConnectPortal"
 Execute-SqlFile "$db_script_dir\UpdateOrder.sql" ".\SQLExpress" "ConnectPortal"
}

task Clean { 
 remove-item -force -recurse $buildartifacts_dir -ErrorAction SilentlyContinue 
}

I like the idea of using PowerShell for automation in projects targeting Windows for two reasons: One, its a real programming language (as opposed to xml), two, more and more things on Windows boxes can be set up and controlled through PowerShell. I want a real language for my build automation becuase it tends to become complicated over time, so sooner or later it I need the power of a programming language. And if the project only targets Windows, then PowerShell is good choice because its simply the Windows command line, and things like IIS, Exchange, SQL Server and so on provide PowerShell interfacfes.

Wednesday, September 2, 2009

Four Bits Worth of Dev Advice: The First Two Bits

This is the second post in a short series of post about developper advice ([1], [3], [4]). The first one listed 16 pieces of advices in the form of headlines. This post briefly explains the first 4:


0000: No bool to bool conversion
I dont know how many times I've seen code that basically converts from one boolean value to another. Like the following (real life, in-production, but obfuscated to protect the innocent) Java script code:


function IsEditorReady()
{
if (editorReady)
{
return true;
}
else
{
return false;
}
}
Why, oh why?
A variation of this is to have some boolean expression as the if-clause. A further variation is to have a series of nested ifs. Or to assign the boolean value to a variable instead of returning it. But still it's just converting something thats already a boolean to ... a boolean. And it's harder to read.


0001: Trust the implementation
When running on top of a big standard library take advantage of that. Don't re-implement the standard library functionality. Don't, for instance, write your very own sting tokenizer because you "want to be sure it works". Firstly you can be pretty sure your version doesn't work in all the corner cases. Secondly its a waste of time. Thirdly it's harder to read, than code using the standard library implementations. So c'mon; take advantage of those huge standard libraries we most often have today.

0010: Declarative over imperative
Writing code is error-prone. Period. But writing imperative code is much more error-prone than writing declarative code. Why? Because imperative code tries to tell the machine what to do step by step (and there are lots and lots of steps), while declarative code tells the machine what the intent is, and leaves the step by step details to the underlying implementation (which we trust, remember?).
Just as importantly declarative code is easier to read, for the exact same reason: It expresses intent, rather the method of reaching the intended goal. Consider this piece C++ of code:

void XYZClient::pushAlarm(const alarm_log &alarm)
{
alarmMutex.lock();
alarmList.push_back(alarm);
alarmMutex.unlock();
}


And then the alternative:


void XYZClient::pushAlarm(const alarm_log &alarm)
{
boost::mutex::scoped_lock lock(alarmMutex);
alarmList.push_back(alarm);
}


The second simply declares that the alarmMutex should be held until the end of the current scope. The first one tries to say when the mutex should be taken, and when it should be released ... and fails at doing so correctly. Granted it's just a matter of adding a try catch ... or is it...what about cases where the call to unlock fails?...oh, the headache.

0011: Beware of vampires
If you open up your doors, vampires will enter and drink your life blood...or in terms of OO software: If a class does not protect it private parts properly some other code will grip them, squeeze them and feast on their last bit of blood...well maybe that wasn't really in terms of software either, but consider this code:


public class Test : AbstractTestElementComposite
{
private readonly IDictionary headerProperties =
new Dictionary<string, string>();

// snip


public IDictionary HeaderProperties
{
get { return headerProperties; }
}


// snip
}


The problem is that the internal headerProperties dictionary is fully exposed by the getter. Oh, there's no setter, but that's just false protection, since vampirish code like this is allowed:


class Vampire
{
void SuckBlood(Test t)
{
t.HeaderProperties.Clear();
t.HeaderProperties.Add(“Alive?”, “Don’t know”);
}
}


This shows that the headerProperties dictionary isn't really kept private in this example. For a thourough write-up on the vampire issue I recommend Kevlin Henneys Encapsulation and Vampires article at StickyMinds.


That it for now, more advice follows.

Four Bits Worth of Dev Advice

Inspired mainly by 2 talks I saw at the JAOO 2008 conference (Kevlin Henney: Programmers Dozen, and Kevlin Henney and Frank Buschmann: 5 Design Considerations) I've put together list of advice for programmers. Such a list could obviously go on and on and on, but the exercise here is to choose the advice that I find most important, and that I see violated time and time again. So I decided to only allow as many pieces of advice as can be enumerated in 4 bits. And here's the raw, unexplained list:

0000: No bool to bool conversion
0001: Trust the implementation
0010: Declarative over imperative
0011: Beware of vampires
0100: Consider infrastructure orientation
0101: Use role based interfaces
0110: Be economic
0111: Prefer code over comments
1000: Use symmetric interfaces
1001: Use one abstraction level per method
1010: Grow guts
1011: Prefer use over reuse
1100: Write change friendly code
1101: Dry
1110: Don’t stay stuck
1111: Be curious

Most, but not all of these appeared in the two talks mentioned above.
I will be posting about all of the pieces of advice in the near future ([2], [3], [4]).

Thursday, August 13, 2009

Exploring a WPF Business Application Architecture 4

I've finally gotten around to starting coding up a little GUI for my little petshop sample. It follows the MVVM pattern. After doing just a couple of windows it's clear that any GUI implemented using MVVM will have a lot of view models and a lot of commands. So where should I put all those classes in terms of folders? I see two possibilities:
  1. Put all the view models in one folder, and all the commands in another folder. There might be more structure below these folders.
  2. Put each view in a separate folder and put the view models and commands belonging to the view in the same folder.
As to what works out best...I'm on the fence...

Sunday, July 5, 2009

Refactoring vs. Re-architecting

I was recently gave a talk about refactoring. Beforehand I was asked to include something about "refactoring on a small scale" and "refactoring on a large scale". And how the two compare. I sort of just accepted that at first, but while preparing the talk I realised that "refactoring on a large scale" doesn't really make a lot of sense: Refactoring is about doing code changes that enhances readability, but doesn't change the observable behaviour of the software. That works out really well for localized changes such as extracting a method, renaming something, extracting an interface etc. But large scale changes (like splitting a single-process-application into several processes working together or moving from a voluntary scheduling scheme to a preemptive scheme) are very different beasts. Such changes aren't just large scale refactorings, they are re-architectings, and very different rules apply to the two.

Contrasting refactoring and re-architecting
To contrast the two let me list some important characteristics of refactoring:
  • Observable behaviour is not changed
  • The goal is to improve readability
  • Refactoring is pretty safe when you have good unit tests around the refactored code
  • Refactoring should be applied in an incremental fashion as a series of small steps
  • Refactoring can usually be done pretty quickly. I.e. the cost is low.
  • Refactoring helps keep the code base clean, which in turn helps keep the team velocity up (this is the real motivation for refactoring)
By contrast I find the following to be some of the important characteristics of re-architecting:
  • Re-architecting is usually done to improve one or more non-functional aspects, such as performance, scalability, availability, etc.
  • Re-architecting thus changes the observable behaviour
  • Re-architecting can't practically be done through a series of small steps. It must be done in a couple of big steps followed by a long series of small (refactoring) steps
  • The big steps are risky
  • The big steps are expensive/time consuming
  • Unit tests don't offer much help when doing the big steps
  • Re-architecting requires all levels of tests to be successful (integration, system, functional, non-functional, automated, manual)
To conclude I think that re-architecting is risky business that should only be done after thorough analysis of the cost vs. the benefit of doing the re-architecting. It's not "just" refactoring on a larger scale. That makes it sound too easy.

Wednesday, June 24, 2009

Exploring a WPF Business Application Architecture 3

It's time to add some DDD style repositories to the pet shop sample's domain model. While I don't want to go down the one-IRepository-fits-all route, I do want to reuse code between the specific repositories. In this post I'll show how to do that using interfaces and extension methods in conjunction to create repository traits that can be mixed and matched to implement specific repositories.

One Size Does Not Fit All
As argued in a nice blog post by Richard Dingwall a one size fits all approach along the lines of:










is not going to work out well: Some of the methods in the one-size-fits-all interface might be inappropriate for some domain classes. So what do we do? -We introduce a number of interfaces each representing specific traits of a repository.

Traits
As proposed by Mr. Dingwall we create a number of interface each specifying one specific trait that a repository might have. Like these:
























and probably others. Now that enables us to pick and choose which traits a specific repository should have. For instance a repository for the pet shops category objects would probably need all the traits listed above, hence it implements all those interfaces:








Incidentally implementing each of these traits is made really easy by Castle.ActiveRecord. All the smae I still don't want to implement them in each and every of the concrete repositories where they are used. This is where extension methods comes in.

Mixins
To be able to provide reusable implementations of the traits I implement an extension method for each method on the trait interfaces:

public static class ActiveRecordRepositoryImpl
{
internal static IEnumerable<Entity> GetAllImpl<Entity>(this ICanGetAll<Entity> self)
where Entity : class
{
return ActiveRecordMediator<Entity>.FindAll();
}

internal static Entity GetByIdImpl<Entity, Key>(this ICanGetById<Entity, Key> self, Key id)
where Entity : class
{
return ActiveRecordMediator<Entity>.FindByPrimaryKey(id);
}

internal static void RemoveImpl<Entity>(this ICanRemove<Entity> self, Entity entity)
where Entity : class
{
ActiveRecordMediator<Entity>.Delete(entity);
}

internal static void SaveImpl<Entity>(this ICanSave<Entity> self, Entity entity)
where Entity : class
{
ActiveRecordMediator<Entity>.Save(entity);
}

internal static int GetCountImpl<Entity>(this ICanGetCount<Entity> self)
where Entity : class
{
return ActiveRecordMediator<Entity>.Count();
}
}
Notice how easy Castle.ActiveRecord makes this. That's nice.
Right; then these *Impl extension methods are used in the concrete repositories:

public class CategoryRepository :
  ICanGetAll<Category>,
ICanGetById<Category, int>,
ICanGetCount<Category>,
ICanRemove<Category>,
ICanSave<Category>
{
public IEnumerable<Category> GetAll()
{
return this.GetAllImpl();
}
public Category GetById(int id)
{
return this.GetByIdImpl(id);
}
public int GetCount()
{
return this.GetCountImpl();
}

public void Remove(Category entity)
{
this.RemoveImpl(entity);
}

public void Save(Category entity)
{
this.SaveImpl(entity);
}
}

And that's it.

So there still the duplication of calling *Impl methods in each concrete implementation method, but the methods actually implementing the repository traits are shared. I think that's pretty nice.

Monday, June 15, 2009

Exploring a WPF Business Application Architecture 2

In my last post I started writing about a pet shop sample I'm putting together to try out a few ideas about structuring business apps using WPF. In this post I'll show the domain model, and I'll show how it's persisted using Castle.ActiveRecord.

The Model
The domain model of the pet shop is shown here:

It's a straight port of the model used in the pet store iBatis.NET sample. I wont go through the model, but just say that it's complicated enough to be interesting as a sample, while simple and small enough to be quick to implement.
For now the domain classes have no behaviour. It's an anemic model. I expect to add behaviour as needed over time.

The Persistence
To exemplify how the model is persisted using Castle.ActiveRecord, I'll show the code of one of the central entities: The category class.











This is a pure POCO, which I think is nice, but ActiveRecord cannot persist instances of category. To make ActiveRecord aware if this a simple attribute is added to the class:





This means that ActiveRecord will be able to create a Category table in the underlying database, but the framework doesn't know which columns the table should have. We tell ActiveRecord what should actually be persisted to the database by adding a few extra attributes:
















All the C# properties that I want to be persisted to the category database table now has an attribute: Simple cases just have a Property attribute and ActiveRecord figures out the rest. The IList is persisted using a HasMany attribute, which means that the product table records will have a foreign key pointing back to the category table. For this to work the product class needs to be an ActiveRecord too.
Lastly notice the Validate* attributes which tells active record to validate certain things before even trying to save the entity to the database.
That's all that is needed to enable the ActiveRecordMediator class to work on my entities. The mediator can now create, read, update, and delete entities/records in the database.

The complete model can be downloaded from here.

Why Use ActiveRecord?
Firstly: It's so easy. There is really not a lot more to it than what I showed above.

Secondly: It's build on the rock solid basis of NHibernate.

Thirdly: The active record pattern is easy to use, easy to understand and actually suits a lot of situation. On the other hand the fact that you follow that one pattern is also the main limitation.

Fourthly: Entities are still almost POCOs. They've just had a few attributes added. This means they are still easily testable, and that I still hjave full control over my inheritance hierarchy. On the other hand the enitities now do two things: They represent a domain concept, and they declare how they are persisted. That's not full-fledged single responsibility. In the cases I have in mind for this exploration though I can live with that.

What's next?
In the next post I'll write about how to read and save ActiveRecord entities through DDD style repositories.

Tuesday, June 9, 2009

Exploring a WPF Business Application Architecture 1

I've been spending some time looking into how to easily build WPF based line-of-business applications lately. To illustrate my thoughts on that subject I'll put together a sample based on the time honored Java Pet store. In this post I'll write a bit about the type of application I'm aiming for, the pet shop, and the architecture I'm aiming for. In a series of following posts I'll show how the domain model, the persistence, the presentation and so on are coded.

So, I'm not trying to figure out how every WPF app should be architected. Far from it. I'm trying to figure out a default architecture for moderately sized business applications. I.e. apps that: Use WPF for presentation, use an SQL Server database for persistence, runs on an intranet, has in the order 100 - 200 unique users, has moderate to large amounts of data (not huge, though), and no special security issues.

To illustrate I'll use a pet shop: The users can browse through categories of pets, put them in their shopping cart, and eventually check out and pay for the pets.

The plan is to use the MVVM pattern which is a variation on MVC, that focuses on allowing for use of WPF's 2-way data binding while still allowing for separation of concerns. The domain model is nicely separated from the view by the view model, which adapts the data in the domain model to the needs of the view. The presentation logic is pulled out of the code behind files to keep it separated from the view itself. All-in-all MVVM delivers a nice structure that allows for good testability and maintainability. To implement this part I might use Caliburn or PRISM or I might do it by hand. I haven't decided yet.
For the persistence of the domain model to the database I'll use Castle.ActiveRecord which is build around Fowler's Active Record pattern: Each domain object is responsible for its own persistence. Each domain class maps to a database table and has CRUD operations. Each domain object corresponds to a database row. Castle.ActiveRecord makes it really easy to use the Active Record pattern: You just have to add a few attributes to the domain classes and their persisted fields and off you go. Your domain objects are still POCOs except for the attributes, so you get to keep your domain object clean and almost-free of infrastructure.
Lastly I plan to throw in Castle.Windsor for dependency injection.

That's it for now. Next post will be about the pet shop's domain model, and about persisting it through ActiveRecord.

Wednesday, May 13, 2009

Can a boy scout be too eager?

The software craftsman movement tells us that as professionals we should strive to do our best. Among other things we should strive to write the cleanest code we can. One of the ways do that is to adopt the so-called Boy Scout Rule. When adapted to software development the Boy Scout Rule goes as follows:

Always leave the code cleaner than you found it

So what does that mean? Well, if I was to simply follow the rule exactly as stated I would always do my best to clean up all the code I came by as much as I could. That leaves me with (at least :-) two questions: Should I really clean up all the code I come across (no), and should I always clean the code as much as I possibly can (no, again). The following paragraphs gives you my thoughts on each question:

What should I clean?
Cleaning everything I come across obviously is not going to get me far: If I use open source library X in a project should I start by cleaning up all the code in X as much as I can? -I think not. Although X might very well be a good and sound project it will inevitably contain a considerable amount of not quite clean or downright dirty code. -Every code base of any significant size does.
So always cleaning up code before using it, would leave me stuck cleaning other peoples working code, while I could have started on my actual project. Not good.
Right, so if I am not going to clean up all the code I meet on my path, then where should I draw the line? I draw the line at code I change: If I change a line of code in a method, I clean up that method, and possibly the class containing it. If I change a couple of methods in class I clean up that class. If I make changes to a couple of interrelated classes I clean up their interaction.

How clean should it become?
In his Clean Code book Uncle Bob goes through an example of cleaning up a class from JUnit (chapter 15). The end result is very nice, and definitely cleaner than the original. But the original was actually pretty good in the first place. Even Uncle Bob thinks so: He writes: "[...] you'll find it [the JUnit code] to be nicely partitioned, reasonably expressive, and even simple in structure". And I agree, the original code is more than decent.
Throughout the chapter Uncle Bob carries on to clean up that code, and ends up with something very different from the original. The chapter ends with the following conclusion: "And so we have satisfied the Boy Scout Rule". I don't agree. Or rather, I think he has over-satisfied the Boy Scout Rule: The code is changed so much that it could be hard to recognize for the original author, which I think is a problem.
The original authors are (in my experience) more than likely to return to the code later. If they can recognize the code, they will probably be able do whatever fix they are there to do pretty quickly. If they cannot recognize the code their work will be a lot slower - even if the new code is cleaner. I think this consideration often outweighs the need to clean up code as much as possible.
Rather I think the quest for clean code should be an incremental endeavour where the code is left a little cleaner each time it's changed, but never changed radically in one go. Over time this incremental cleaning might very well change the code to the point of being unrecognizable to the original authors, but only if they have not followed or taken part in the incremental clean up. In that case they have effectively stopped particpating in the maintainance of the code, so slowing them down is not such a big deal.

Conclusion
We should, in general, strive for writing the cleanest code we can. The Boy Scout Rule helps us do exactly that, but don't be too eager: Don't clean up code you are not already changing for other reasons. And don't clean up code to the point of being unrecognizable. 

Monday, May 4, 2009

DCI in C#

The DCI, or the Data Context and Interaction is an approach to implementing domain logic and use cases in terms of the roles domain objects play at runtime. It is being developed and promoted by Trygve Reenskaug and James O. Coplien, who have written a very good introductory article about DCI at Artima.com. Here I'll stick to a very brief explanation and then jump into implementation of DCI in C#.

DCI at a Glance

I find that the DCI design is most easily understood in the context of Model View Controller. MVC, in its purest form, allows the end user to reach through the view, via the controller into the model and manipulate it directly. This is fine as longs the user is actually able to perform his tasks simply by massaging the domain objects. As soon as the application needs to support some sort of coordinated sequence of actions that the user is not allowed to control on his own,  something more is needed. Where is that control coded? Is it in the controller? Is it spread out between a number of domain classes? Is it in a business or service layer on top on the domain model? -DCI offers a different take:
DCI tells us to think in terms of three main concepts: The data captured in the domain model, the interactions between domain objects happening at runtime and the context in which the interactions happen. DCI also tells us to implement interaction in terms of roles: Domain objects take on different roles throughout the execution of an application. The interactions between domain objects happen in terms of these roles. The context of an interaction is the collection of runtime objects that will take part in the interaction, each referenced by role. The nice thing is that those coordinated sequences of actions are implemented directly in the role that will plays the lead part in the interaction. The context will provide the role with all the collaborators it needs. 
Right, enough explanation, the article mentioned above does a better job at explaning DCI anyway, so I'll just jump right into the C# code.

The C# Code

I'll walk through how the data, the context, and the role can be implemented in C#. To do this I'll use a simplistic banking example and implement a simplified money transfer use case in the role TranferMoneySource. The example is the same as the one used in the article linked above.
The domain model (i..e the D in DCI) consists of a savings account and an abstract account:

public abstract class Account
{
   public double Balance { get; protected set; }

   public void Withdraw(double amount)
   {
       Balance -= amount;
   }

   public void Deposit(double amount)
   {
       Balance += amount;
   }

   public void Log(string message)
   {
       Console.WriteLine(message);
   }
}

public class SavingsAccount 
    : Account, TransferMoneySource, TransferMoneySink
{
    public SavingsAccount()
    {
        Balance = 1000;
    }

    public override string ToString()
    {
        return "Balance " + Balance;
    }
}

The TransferMoneySource and TransferMoneySink are roles, and I'll get back to those. For now just notice that the roles must be interfaces, since the single inheritance of C# is used to extend the abstract Account.
The context (the C) in which the money tranfer use case is executed is the TransferMoneyContext:

public class TransferMoneyContext
{
    public TransferMoneySource Source { get; private set; }
    public TransferMoneySink Sink { get; private set; }
    public double Amount { get; private set; }

    public TransferMoneyContext(TransferMoneySource source,
        TransferMoneySink sink, double amount)
    {
        Source = source;
        Sink = sink;
        Amount = amount;
    }

    public void Execute()
    {
        Source.TransferTo(Sink, Amount);
    }
}

The context captures the objects necesarry to execute the money transfer use case in terms of the roles they play in that use case. I.e. the context captures the account that acts as source and the account that acts as sink. The context just holds on to these object until the Execute method is called. At that point the control is transferred to the role capable of running the use case - the source account.

Lastly the role implementation remains. The use case (the I) is captured in the role, and the role is attached to any number of domain objects.  As mentioned above the roles are interfaces, but they also need to implement the use case. This is achieved through extension methods attached to the role interfaces. This enables us to tie behaviour to interfaces, which is what we need in order to tie the use case implementation to the role, which in turn can be tied to any domain object. The roles are implemented like this:

 public interface TransferMoneySink
{
    void Deposit(double amount);
    void Log(string message);
}

public interface TransferMoneySource
{
    double Balance { get; }
    void Withdraw(double amount);
    void Log(string message);
}

public static class TransferMoneySourceTrait
{
    public static void TransferTo(
        this TransferMoneySource self,
        TransferMoneySink recipient, double amount)
    {
        // The implementation of the use case
        if (self.Balance <>
        {
            throw new ApplicationException(
                "insufficient funds");
        }

        self.Withdraw(amount);
        self.Log("Withdrawing " + amount);
        recipient.Deposit(amount);
        recipient.Log("Depositing " + amount);
  }
}

In essence the above usage of extension methods on interfaces emulates traits in C#.

DCI on .NET

While this offers one way of doing DCI on the .NET platform it is not the only way. There are also implementation in Python and Ruby. Attaching roles to objects is somewhat more straight forward in Ruby, where it is done by mixing a module specifying the a role into a domain object at runtime. With IronRuby maturing nicely, that could easily turn out to be the nicer DCI implementation for .NET.