Application structure
Every new application we’re trying to raise from scratch, especially when it’s a big one, we’re drawn to the basic questions of how to structure our code so it will be easy to maintain, easy to extend and easy on the eyes(= it makes sense). This post is meant for teams with more than 4 programmers working on the source of a 2+ (human) years project. If you work alone and the client doesn’t really care, heck, you can do it in one big assembly and name it [your_name]Rules.
I’ve discovered along the years that it really bothers me to see unorganized solutions or bad naming. I call it “structure smell” and as you might have guessed, I’m a sensitive guy. I’ve structured my thoughts about the way I see things so I could use it later on as a reference for myself and for my Team. Before I’ll continue, keep in mind that most of these questions are philosophical, so there is no one holy answer, it’s just a matter of point of view. I tried to point out best practices based on my experience. In addition, instead of writing user-story\feature\requirement\bug fix\UI change\you-name-it, I would use the term “task” instead. I’ll even go one step further and say that a given task should be limited to 0.5-1.5 days so it would be easy to see progress over time(if you’re on the agile boat as I am) and help us focus on the domain\context we’re working at during the task.
Enough said, let’s get going:
“Should we build one big solution?”
The immediate answer on this one is absolutely not.
The quick reason behind it as no matter what you do, while working on a task, you usually don’t need all of the projects at the same time. I see no reason to compile so many projects if you’re working only on 2-3(or even 5-6) of them at a time. I know that Visual Studio .Net is smart enough to avoid needless compilation of projects that we’re not changed, but keep in mind that John, your teammate, is working on different tasks than you are which means that he can make some changes, checked them in and your next “Get Latest Version” might cause unnecessary compilation on your side. If you haven’t noticed(who am I kidding), VS.NET can become an heavy memory consumer for big solutions, add to it our beloved ReSharper(that must analyze all of the projects in the solution to give you smart ideas), it can get quite messy.
The second reason, is simplicity. Why looking at 40 projects when you need only just a few? sure, you can collapse them or even organize them in Solution Folders(in VS.NET 2005), but it’s much easier to keep the noise out.
“So How should we split our solutions and projects?”
On this scale of projects, it would not be a great idea to create projects based on layers (DataAccess project, Business layer project, UI project etc). This way, each layer(=ClassLibrary) would be filled with too many classes and in time, it will be hard to find your path in one project with more than 200 files in it. Another bad side effect for splitting the projects by layers is that it will narrow the way you think about solutions (to problems). Instead of trying to create pure OO components you’ll immediately start breaking one piece into “this is UI, this is BL, this is DAL” and possibly branch your code into the wrong assemblies by cold 0 or 1 decisions. Life is one big gray CLR.
So I’ll try to define the way I see solutions, projects and namespaces and how should we use them:
1). Solution represent a domain in your application.
Domain is a complete sub-system in the application. It’s much bigger than a single component and it’s usually bind a list of components into one large sub-system that we can address as one big black box. The sub-system expose interfaces to other sub-systems in the application.
If I had to develop Lnbogen’s Calendar for example, I would consider these sub-systems: Common, Engine, DataStorage, Site, Widgets. Each one of these sub-systems deserves it’s own solution.
2). Project is a component in that domain or a mini-sub-system in the application.
A component is a all-around solution in a specific domain. The consumer of the component expect it to perform its task from A-Z even if that requires some of interaction with other objects. It should be transparent to the component’s consumer. Let’s say that we have a Calendar component, I would like to be able to call myCalendar.CreateNewMeeting(user, [meeting details]…) without taking care of insert it to the database, update some sort of cache(if exists) or to trigger alerts manually in case of collision. I expect the component to provide a full solution to my problem. Obviously, we don’t expect the Calendar to save the meeting to the data storage by it’s own but rather to receive some sort of IDataSource that will take care of it, but that should be made behind the scene as the purpose is to expose complete functionality.
In addition, a project might be “Entities” or “Utilities” where in these scenarios, the project represent a mini-sub-system.
3). Namespace group components and types under the same domain or “logic context”
Namespaces allow us to group types that are logically belong to the same domain and create a proper hierarchy so the programmer could easily find is way around the available types.
“What about naming?”
Naming is crucial for a few reasons: (A) It ables us to quickly understand the purpose of an assembly\class\method as its consumers, (B) good naming of classes\methods => less documentation => more 1:1 between your docs & your code and (C) it helps you to keep the most important principle of coding – be proud of your (and your team’s) code. It’s a beautiful thing to see Semingo.[…]. I’m loving it!
Naming rules:
1). Name your solutions by the domain they represent.
2). Name your projects by the components or mini-sub-system they represent. Template: [CompanyName].[Application].[ComponentName\MiniSubSystem]
3). Name your namespaces by the domain they group (the types) by.
Example (Lnbogen’s Calendar):
Directories tree:
– Lnbogen
– Calendar (root Directory)
– build
– v1.0
– v1.1
(etc)
– tools
(list of assemblies, exe or other 3rd party components you might use)
– documents
– db
(maybe backup of database files for easy deployment)
– src
– Common
| Common.sln
– Lnbogen.Calendar.Entities
– Lnbogen.Calendar.Entities.Tests
– Lnbogen.Calendar.Utilities
– Lnbogen.Calendar.Utilities.Tests
– Engine
| Engine.sln
– Lnbogen.Calendar.Framework
– Lnbogen.Calendar.Framework.Tests
– Lnbogen.Calendar.TimeCoordinator
– Lnbogen.Calendar.TimeCoordinator.Tests
– Lnbogen.Calendar.RulesEngine
– Lnbogen.Calendar.RulesEngine.Tests
– Lnbogen.Calendar.Service (*1)
– Lnbogen.Calendar.Service.Tests
– DataStorage
| DataStorage.sln
– Lnbogen.Calendar.DataStorage.Framework
– Lnbogen.Calendar.DataStorage.Framework.Tests
– Lnbogen.Calendar.DataStorage.HardDiskPersisenceManager
– Lnbogen.Calendar.DataStorage.HardDiskPersisenceManager.Tests
– Lnbogen.Calendar.DataStorage.WebPersisteneceManger
– Lnbogen.Calendar.DataStorage.WebPersisteneceManger.Tests
– Lnbogen.Calendar.DataStorage.DatabasePersistenceManager
– Lnbogen.Calendar.DataStorage.DatabasePersistenceManager.Tests
– Lnbogen.Calendar.DataStorage.Service (*1)
– Lnbogen.Calendar.DataStorage.Service.Tests
– Site
– Lnbogen.Calendar.UI
– Lnbogen.Calendar.UI.AdminSite
– Lnbogen.Calendar.UI.UserSite
– Widgets
– Lnbogen.Calendar.Widgets.Framework
– Lnbogen.Calendar.Widgets.Interfaces (for plug-ins support)
– Lnbogen.Calendar.Widgets.Service
(more directories per widget)
– Integration
– Lnbogen.Calendar.Integration.InternalWorkflow.Tests
– Lnbogen.Calendar.Integration.ExternalWorkflow.Tests (test that the services we expose to the world work as expected)
– References
(here you should put all the dlls that you use as “file reference” in the various solutions)
*1: for example, this could be WCF wrapper of the underlying engine that enable other internal components to talk with the CalendarEngine\DataStorage as one complete component.
You can notice that I’ve chosen to drop the “Engine” or “Common” while selecting the name of the directories. “Common” is not really a domain but rather a logic separation of things that belong to many domains (usually all of them). “Engine” is the real deal, there is no Calendar without the engine right? So in this case I feel comfortable to drop the obvious (Lnbogen.Calendar.Framework won’t sound better as Lnbogen.Calendar.Engine.Framework).
Solution structure:
In VS.NET 2005, there is a nice feature named “Solution Folder” (right-click on the solution->Add->New Solution Folder) which is a lovely way to group projects. The Solution Folder is a virtual folder(you won’t see it on your HD) so you don’t have to get worried about too much nesting.
Here is the pattern I love to use, demonstrated on the Engine.sln:
Engine (Solution)
_Core (Solution Folder) (*2)
– Lnbogen.Calendar.Framework
– Lnbogen.Calendar.TimeCoordinator
– Lnbogen.Calendar.RulesEngine
– Lnbogen.Calendar.Service
Tests (Solution Folder)
– Lnbogen.Calendar.Framework.Tests
– Lnbogen.Calendar.TimeCoordinator.Tests
– Lnbogen.Calendar.RulesEngine.Tests
– Lnbogen.Calendar.Service.Tests
ExternalComponents (Solution Folder)
– Lnbogen.Calendar.Entities (via “Add existing project”)
– Lnbogen.Calendar.Utilities (via “Add existing project”)
3rdPartyComponents (Solution Folder)
– (Open Source projects that I might use will go here)
Solution Items
(add any dll that you use as file reference in this solution)
*2: The reason I’m using “_” is to make sure it’s the first Solution Folder. I just think it’s more productive way of looking on your projects. I use the same thing for my interfaces and call the file that contains them _Interfaces.cs.
On the next post, I’ll try to focus on strong naming and versioning of assemblies.