Namespace Design Technique, Structuring Your Libraries Using Test Driven Development

By now, I’ve probably interviewed a decent amount of developers, over the years, to fill in positions that we have in our company. One thing I’ve noticed though, in job interviews, is that when you ask people about “namespaces”, what they are for? They usually know the concept, you know, essentially is a way to organize your classes, member types, into logical groupings. That’s true, however, most programmers would lay artifacts as they “think” they fit within a single namespace; without actually caring for framework design guidelines. When designing APIs, the member types that reside within your namespace can be taken to a different design level from a framework design perspective with the purpose of making your libraries easy to use, and yet conform with standards in your organization and products. This is very useful, specially when you have large libraries containing lots of artifacts. Namespaces play a big role as they lay down the ground for organizing your features. From the most common to the most complex.

Structuring Namespaces Based on Scenarios

A technique suggested by Microsoft architects Krzysztof Cwalina and Brad Abrams, on their book, Framework Design Guidelines, Second Edition. A scenario structure based assembly, which conforms a set of common type functionality from multiple features that resides in the most outer namespace according to complexity. So the more complex the operation is, the deeper level it resides on. Basically, you’ll end up having on the main namespace, types that support the most common scenarios, whereas inner namespaces contain scenarios for other complex or specialized functionality.

Classes defined in namespace A shouldn’t depend on other inner namespace classes defined on A.A.1, A.A1.A2 – A.B1, A.B1.B2. The same applies for a case like a class from namespace A.B1.B2 shouldn’t depend on a class from A.A1.A2. If so, you might as well move it to the outermost namespace between those two; in a case like the one above, it’ll be on namespace A. It is a good practice not to get hierarchal too deep as this adds complexity to your design. I’d suggest to keep it as simple as possible, like having no more than three levels like the sample above might be a good idea but obviously it depends on your API design and the layer architecture you’re using.

Determining What Goes Where?

Following this guideline, if you’re not sure what to put under your namespaces and even if you’re not sure how to layout your namespace hierarchy, there is coding technique that can help you get a grasp determining simple, advance and complex scenarios. TDD (Test driven development) is almost the best approach to resolve this. Start by writing the code you want a developer to write is the place to begin. This is probably the tricky part, but with care, you can easily determine the initial object model of your library. You write the code you need or think is good and then work backwards to figure out the object model.

First off, try to come up with 3 or 4 common scenarios, once you have that, see if you can abstract an object model. Get as many object models as you can possibly deliver to cover most of the features needed. But make no mistake coming up with scenarios is not as easy as you might think because that is a combination of technical skills and knowing the requirements.

Make sure that the API design specification in the central part of the design of any feature. There’s much to blog about in regards to API design, however that’s another post, meanwhile, let’s start by at least understanding, how we should structure namespaces based on common scenarios.