SharePoint (2007 or 2010) Architecture - Part 1: Building a case for quality

In the wild, the development of SharePoint customizations is still a bit like the Wild West when compared to where things are at with other forms of modern software development. I'm not blaming the developers or even the architects for this dilemma because developing and deploying custom software for SharePoint can be difficult - a bit like trying to swim against a strong tide. In this article I would like to explain some simple concepts that might make your overall SharePoint development and maintenance experience more bearable.

Note:
If you are developing solutions for SharePoint then you should also read my other SharePoint development articles and, in particular my article about using your build server to help make the process of deploying your customizations much nicer.

What is architecture?
Architecture refers to things that are designed and made by people. And the design is generally a carefully planned thing. This allows us to logically separate between things that a child might build with Lego, mud or clay and, let's say, the structure of a well-designed chair or a house.
Sometimes the code that gets deployed to SharePoint shares more in appearance with mud pies or messy piles of Lego than with a well-planned and organized room.
To be of a high good quality, it is required that both the architectural underpinnings of your code be strong and firm and also that the organization be consistent and well formed.

Note:
Fowler suggests architecture is the things that the senior developers on the team agree are probably important, and are hard to change. Re: the house, the architecture might be the direction it points, and whether it is one storey or two. The organization of the room is just code that's easily changed.

Why is architecture important?
Let's say that you produce a single web part and that you deploy it into SharePoint. For the next month or so you might get some change requests and you are happy to wear the pain of re-deploying it and everybody is happy. But multiply that pain by 3 or 4 (or more) developers and by 4 or 5 (or more) applications and by 3 or 4 (or more) features... and you are already in living, developer hell. And that's even before the first round of maintenance comes along from your initial deployments.
At this point in time - and I'll ask you to take another look at that scoop of spaghetti in the image - your agility and therefore your ability to change is gone! Before you know it, you are unable to meet the demands of the business and you are spending your nights working out how 4 year old code works.
Identifying good and bad code?
There are some worrying signs to look out for and code smells that you can observe in your SharePoint code repositories if you are hoping to avoid the aforementioned road to hell.

• Your web part classes have database access code in them
• Your web part classes have intimate knowledge of how to configure things
• Your web part classes have more than a couple of methods

They are the commonsense metrics, now let me give you my gut-feel metric:

• If you have more than 120 lines of code - in total - in your web part class file then that is a "smell" and needs further investigation. And yes, that includes Namespace declarations and everything!

If we apply good architecture and code organization techniques to our SharePoint coding, then our code will be well factored and easily understood across the whole team. It will be easier to change and manage.
How chaos occurs – a short walk through

A day comes when you need to develop a new Web Part and add it to your solution. You might come up with an idea for this web part and then ask one of your developers to implement it. Let's suggest that our code has an unclear architecture and that the organization of it is untidy. What will the developer deliver?
He may decide to implement a single web part class with lots of code in it. Code which connects to a database, grabs some data, caches it, and then sets out to render the user interface of the web part by reading through whatever object the database returned.
Alternatively your developer may choose to start creating a bunch of classes within your solution to do things. But what are these classes? What are they called? And are we happy with the concepts that are being introduced?
I'm not saying that any of these things is necessarily the wrong thing, but in the absence of specific guidance and existing patterns, you can see how things can get rather messy indeed.
What you want is that, when you ask for the web part, you will know pretty much exactly what will be delivered in terms of a final set of artifacts.  So that what is built when creating one web part will be the same as what is built when creating the next one. Building upon common foundations and delivering with consistent organization.
Taking the architectural path
Think of your web part as you would any other architectural artifact and layer your software so that you have a sensible separation of concerns between each of the different functions within your application. But don't start by thinking that you have to build something that is perfect, there is no perfect. Perfect is whatever works best for you and your team. But we still need to work along common patterns and standards, so let's start with the some age old sensibilities and separate things along the lines of:

• Models (getting our hands on the data)
• Views (showing awesome stuff to our users)
• Controllers (orchestrate the processes between data and view to ensure that things run smoothly)

Notice that I didn't mention anything about choosing your favorite IoC container or how to create Mock classes for testing? I'm just skimming across the top - because I am assuming that your team needs time to learn how to get better. The low hanging fruit is what is important when you are trying to improve your coding standards... you don't need to start at the lowest level. 
My suggestion is that, when you are starting your improvement journey, be pragmatic, start somewhere around halfway between heaven and hell. Because premature optimization is the root of all evil, and, while you can try to start out by cramming every concept that you’ve ever read about into your architecture right from the beginning, a lot of the time patterns within those architectures are put in place to solve problems that you may never even experience. So while your architecture might feel elegant... you ain't gunna need it!
In the next article I will talk through a specific implementation for a SharePoint Web Part and highlight its benefits.