Standardize Your .NET Namespaces
Namespaces can help you organize your company's .NET source code, but only if you have a solid plan.
by Jonathan Goodyear, MCSD, MCP, CLS

April 2003 Issue

Remember how difficult it was in the COM world to organize the source code for your enterprise? You typically only had two naming levels to work with: project name and class name. All too often your ProgIDs ended up looking like this:

XYZCompanyAccounting.Payroll

Obviously, this is not ideal. It would be better if you could separate the namespace identifier more. For example, ProgID might be represented in .NET this way:

XYZCompany.Accounting.Payroll

The difference is subtle in this case, but the difference becomes more apparent as you define deeper project hierarchies.

The fact that the .NET Framework offers you the ability to create more deeply nested namespaces can make things much better for you—or much worse. Reaping the benefits of deeply nested namespaces requires careful planning and consideration, as well as coordination among the various development groups in your organization. This article offers you some helpful suggestions to organize your enterprise .NET source code, both in namespace form and in Visual SourceSafe (VSS) projects.

Structure Your Namespaces
As a helpful starting point, each namespace that you assign to a unit of source code should begin with a company identifier. For instance, my previous example begins with "XYZCompany." The next section of your namespace depends on the intended scope for the code. If the code is business logic–specific to a project, then the next section of your namespace should be the name of your project ("Accounting," in this case). Following that is the specific subsection of your project ("Payroll," in this case). This means your project-specific namespace should be:

XYZCompany.Accounting.Payroll

You can then tailor the classes within the XYZCompany.Accounting.Payroll namespace to the more specific tasks at hand. By segmenting business logic namespaces on a more granular basis, you can divide your code into more specific project units in VSS (more on that later).

ASP.NET Web projects and Web services projects are special cases of project-specific namespaces. A good standard to follow for ASP.NET Web projects is CompanyName.ProjectName.Website. Likewise, a good standard namespace format for a Web services project is CompanyName.ProjectName.WebServices.

Following this syntax, the namespace for XYZCompany's accounting Web site and Web services would be:

XYZCompany.Accounting.Website
XYZCompany.Accounting.WebServices

The namespace scheme you use can vary, depending on the intended scope of the source code. If you intend the code to be shared across the enterprise, don't factor project names into the namespace name. I also suggest you don't create your own naming standard. Instead, follow the standard that Microsoft has established already for the .NET Framework. For instance, if the developers at XYZCompany are building an enterprise class library to encapsulate data access to SQL Server, they should give it this namespace:

XYZCompany.Data.SqlClient

This namespace models the System.Data.SqlClient namespace structure in the .NET Framework. Likewise, if developers at XYZCompany build a class library to encapsulate their own custom event logging process, this namespace would be appropriate:

XYZCompany.Diagnostics

It's always good to create unique class names within your namespace. That way, you won't end up with class name collisions if it becomes necessary for your code to use both the .NET Framework namespace and a company-specific namespace simultaneously. For example, instead of naming your custom event log class EventLog, consider calling it EventLogger or XYZEventLog. I prefer the former suggestion because it's superfluous to list the company name more than once in the fully qualified class name.

It's important to build your namespaces in this format for several reasons. First, by establishing a namespace root of your company name, you eliminate the possibility of namespace collisions with third-party products that you might purchase in the future. Second, by adopting the same namespace hierarchy as the .NET Framework, you make it easier for your developers to find classes in your company's infrastructure that support the functionality they need. Microsoft's class cataloging system might not be perfect, but it makes no sense to force your developers to learn a second system that's specific to your organization. Third, by building a namespace hierarchy for your organization, you can easily compile a single MSDN-style documentation file for your entire class library using a documentation generation tool, such as NDoc.

Structure Your Projects
Now that you have your namespace format in order, you might be wondering how your projects should be structured in VSS. I suggest two top-level project nodes in your VSS tree:

XYZ Enterprise .NET Class Library
XYZ Project .NET Class Library

Figure 1. Name Your Project Nodes.

The two top-level project nodes allow you to create two separate documentation files (one for project-specific code and one for enterprise code). Under each top node, create a project node for your company name (XYZCompany, in this case). This is your root namespace. For the remainder of the VSS project tree, duplicate the namespace structure that you have created, replacing the dots (.) in your namespace names with folder boundaries—similar to how Java class hierarchies are represented by dots in code and folders in the CLASSPATH system environment variable (see Figure 1). Remember always to name your project files themselves using the fully qualified, complete namespace name.

While I'm on the subject of naming standards, let me advise you to adhere to some of the class name suffixes that Microsoft has established already. For instance, attribute classes should all end with the word "Attribute," and exception classes should all end with "Exception." What this means, essentially, is that before you decide on a name for a class you're going to build, determine what type of class it is going to be and check the .NET Framework class library to see whether a naming standard exists already. If it does, follow it.

The namespace structure I've outlined is merely a suggestion to help you organize your enterprise's .NET source code. .NET is fairly new in most companies, so now is the ideal time to put an organized cataloging system into place. The important thing to take away from this article is the importance of establishing a standard naming structure for your namespaces. Otherwise, your .NET code will wind up being a deeply nested version of the disorganized ProgID code library you're probably struggling with now.