Namespaces, namespaces and more namespaces

Some random thoughts and suggestions follow regarding how you design the namespaces that your classes fit into when writing APIs that other developers will utilise.

Many of these points I’ve recently been dealing with myself whilst having a team of developers joining a team I’m working in; when documenting some of the API and framework, I realised that it was not as easily discoverable or navigable as it could be; the next time I work on a reusable API, I’ll bear these points in mind more. I’d also recommend having a read of Framework Design Guidelines, which I read not too long ago and really opened my eyes in a number of ways to framework design.

  • Make your classes discoverable. I can’t stress this enough. The namespaces of your API should be easy to navigate, logically laid out and as readable as possible. Put yourself in the shoes of another developer who types MyApplication. in Visual Studio. When they press that “.” key, Intellisense is going to pop up and show them the different areas they can look through. This needs to be as clear as possible in order to guide them through the API; when I start trying out a new API, Intellisense is my first port of call – I certainly don’t start by reading all the documentation on every class.
  • Distinguish between 80/20 classes. It’s tempting to simply place all your classes that fulfil a particular function into a single namespace, but this often doesn’t help the developer. Instead, consider making a sub-namespace which contains more advanced features or classes (used 20% of the time) and keep the more common ones (used 80% of the time) at the higher, more easily discoverable, namespace. Also be strict regarding encapsulation – don’t make classes / methods / properties etc. public unless you need to.
  • Do not use department names in your namespace. Physical departments are always changing. At the end of the day they usually really have nothing to do with your API. If your department is restructured or renamed, will your code magically stop working? I would even go as far as to say for internal applications, do not include the company name either – what’s the point.
  • Beware of rigidly following the “namespace must be a child of the assembly name rule”. If we had an assembly called e.g. “MyApplication.Framework”, all code in that assembly should theoretically go underneath the MyApplication.Framework namespace. However, as an API developer, you might want very frequent and popular classes not to be buried away underneath the Framework level – you might want a developer to simply type “MyApplication.” and see the 4 or 5 most important classes that your API has to offer because that’s all that they might need most of the time. Indeed, they might have nothing to do with one another in terms of functionality – perhaps one is to do with logging, another to do with eventing etc.. It might sometimes be better to have an assembly which does not following the System.Subsystem.BlaBla naming convention and instead is simply called “BlaBla” – you’re not implying a namespace from this so are free to put stuff in any namespace.
  • Don’t be concerned with file navigation. Don’t worry that the developer cannot infer at a glance what assembly a particular class lives in. They can hit F12 and be transported to the source code (or metadata) of the class immediately; they can use Solution Navigator to find the file, or have Solution Explorer follow the active file etc.. That should not be your main concern when designing your API.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s