Namespace Naming

Identifier naming is important when you write code. That applies to all kinds of identifiers such as namespaces, classes, functions and variables. Identifiers that only exist in smaller contexts such as local variables inside small functions can be short and require less consideration than other names.

Namespace names exist in very large contexts, thus you should take great care when you name them. Microsoft has some guidelines that I generally find sound:

• http://msdn.microsoft.com/en-us/library/ms229026(v=vs.110).aspx
• http://msdn.microsoft.com/en-us/library/893ke618(v=vs.71).aspx

So where do we as developers fail when naming namespaces? The following is what I have seen:

• Long namespace components concatenated of less well-considered words. Long namespace components are a bad smell, probably an indication of ‘I could not really decide on a good name’. Take an example from one of the links: Microsoft.Media; the Media component is short and (hopefully) precise for what the namespace contains. In general, names should not fully describe what they refer to; they are, well, just a reference. So take a step back and come up with a good short name. If you rename a namespace, some of its contents may have to move to another namespace due to the name change – and that can be a good thing.
• Namespace components that either contain or just are generic insignificant words like Base, Common, Framework, Platform, Shared, Tools, Utility, Manager, etc. In my mind, there typically is no justification for using such words. A way to get rid of them is to move the contained functionality to the parent namespace.
• Namespace components containing short-lived words like product names or organisational names. As such, namespace components typically are high up in the namespace hierarchy, it can take a lot of work to rename them (at least if you lack a good refactoring tool). A rule of thumb is to use names that describe what a namespace contains, not where it is used or what it is used for.
• Namespace components containing software layer names. If your code really is partitioned according to software layers, I would to some extent argue that you got it wrong. In the extreme case, it would mean that all software projects would have the same namespace hierarchy. I guess that code in a specific software component should generally pertain to a single software layer such that the associated software layer is more like an attribute of the software component, but the name is a different thing.
• Repeated namespace components. That might seem as a trivial thing, but I have often seen that the same name or a variant of it is somehow repeated. My recommendation is to avoid that and keep your namespace names short.

To sum it up, use short carefully authored namespace names.

What about hierarchy? The above links also have guidelines for that. One point that I think is really important is this one:

"A nested namespace should have a dependency on types in the containing namespace. For example, the classes in the System.Web.UI.Design depend on the classes in System.Web.UI. However, the classes in System.Web.UI do not depend on the classes in System.Web.UI.Design."

Thus, code can depend on code in a containing namespace, but not the other way around. Many, many people violate this guideline. Often I have seen a top-level class composing its behaviour by combining functionality from code located in child namespaces. That is wrong. Have a look at the .NET framework and probably most Java standard libraries. Without knowing them in detail, I assume they do not violate this guideline.

And now to a controversial suggestion. Do not short-circuit your namespaces. What I mean by this is to avoid using statements like 'using MyCompany.MyProduct.MySomething;' (C#) and 'import mycompany.myproduct.mysomething.*;' (Java); use the fully qualified names. Okay, I am not that radical, I would not recommend that in all cases. The compromise I have tried to apply is to short-circuit namespaces for identifiers in all but my own code. How well this suggestions works depends on the programming language you are using and its name resolution rules. In languages like C++ and C#, you can use an identifier from a parent namespace without any qualification. And if you stick to the rule of using short namespace names and using a proper hierarchy structure, you will often only need to qualify identifiers with a single identifier.

The benefits are that your code becomes easier to read and that you can use really short identifiers, as you do not have to anticipate that in a minute you will short-circuit your own carefully authored namespace. Thus instead of having to prefix class names with parts of the containing namespace to avoid name clashes, then in namespace 'MyCompany.MyProduct.Rfc822' you will just name your class 'Message' instead of 'Rfc822Message'. In my view that is elegant and was the intention behind namespaces.