Should the folders in a solution match the namespace?

Question

Should the folders in a solution match the namespace?

In one of my teams projects, we have a class library that has many sub-folders in the project.

Project Name and Namespace: MyCompany.Project.Section.

Within this project, there are several folders that match the namespace section:

• Folder Vehicles has classes in the MyCompany.Project.Section.Vehicles namespace
• Folder Clothing has classes in theMyCompany.Project.Section.Clothing namespace
• etc.

Inside this same project, is another rogue folder

• Folder BusinessObjects has classes in the MyCompany.Project.Section namespace

There are a few cases like this where folders are made for "organizational convenience".

My question is: What's the standard? In class libraries do the folders usually match the namespace structure or is it a mixed bag?

Answer 1

No.

I've tried both methods on small and large projects, both with single (me) and a team of developers.

I found the simplest and most productive route was to have a single namespace per project and all classes go into that namespace. You are then free to put the class files into whatever project folders you want. There is no messing about adding using statements at the top of files all the time as there is just a single namespace.

It is important to organize source files into folders and in my opinion that's all folders should be used for. Requiring that these folders also map to namespaces is unnecessary, creates more work, and I found was actually harmful to organization because the added burden encourages disorganization.

Take this FxCop warning for example:

CA1020: Avoid namespaces with few types
cause: A namespace other than the global namespace contains fewer than five types https://msdn.microsoft.com/en-gb/library/ms182130.aspx

This warning encourages the dumping of new files into a generic Project.General folder, or even the project root until you have four similar classes to justify creating a new folder. Will that ever happen?

Finding Files

The accepted answer says "The classes will be easier to find and that alone should be reasons good enough."

I suspect the answer is referring to having multiple namespaces in a project which don't map to the folder structure, rather than what I am suggesting which is a project with a single namespace.

In any case while you can't determine which folder a class file is in from the namespace, you can find it by using Go To Definition or the search solution explorer box in Visual Studio. Also this isn't really a big issue in my opinion. I don't expend even 0.1% of my development time on the problem of finding files to justify optimizing it.

Name clashes

Sure creating multiple namespaces allows project to have two classes with the same name. But is that really a good thing? Is it perhaps easier to just disallow that from being possible? Allowing two classes with the same name creates a more complex situation where 90% of the time things work a certain way and then suddenly you find you have a special case. Say you have two Rectangle classes defined in separate namespaces:

• class Project1.Image.Rectangle
• class Project1.Window.Rectangle

It's possible to hit an issue that a source file needs to include both namespaces. Now you have to write out the full namespace everywhere in that file:

var rectangle = new Project1.Window.Rectangle();

Or mess about with some nasty using statement:

using Rectangle = Project1.Window.Rectangle;

With a single namespace in your project you are forced to come up with different, and I'd argue more descriptive, names like this:

• class Project1.ImageRectangle
• class Project1.WindowRectangle

And usage is the same everywhere, you don't have to deal with a special case when a file uses both types.

using statements

using Project1.General;  
using Project1.Image;  
using Project1.Window;  
using Project1.Window.Controls;  
using Project1.Shapes;  
using Project1.Input;  
using Project1.Data;  

vs

using Project1;

The ease of not having to add namespaces all the time while writing code. It's not the time it takes really, it's the break in flow of having to do it and just filling up files with lots of using statements - for what? Is it worth it?

Changing project folder structure

If folders are mapped to namespaces then the project folder path is effectively hard-coded into each source file. This means any rename or move of a file or folder in the project requires actual file contents to change. Both the namespace declaration of files in that folder and using statements in a whole bunch of other files that reference classes in that folder. While the changes themselves are trivial with tooling, it usually results in a large commit consisting of many files whose classes haven't even changed.

With a single namespace in the project you can change project folder structure however you want without any source files themselves being modified.

Visual Studio automatically maps the namespace of a new file to the project folder it's created in

Unfortunate, but I find the hassle of correcting the namespace is less than the hassle of dealing with them. Also I've got into the habit of copy pasting an existing file rather than using Add->New.

Intellisense and Object Browser

The biggest benefit in my opinion of using multiple namespaces in large projects is having extra organization when viewing classes in any tooling that displays classes in a namespaces hierarchy. Even documentation. Obviously having just one namespace in the project results in all classes being displayed in a single list rather than broken into categories. However personally I've never been stumped or delayed because of a lack of this so I don't find it a big enough benefit to justify multiple namespaces.

Although if I were writing a large public class library then I would probably use multiple namespaces in the project so that the assembly looked neat in the tooling and documentation.

Answer 2

Also, note that if you use the built-in templates to add classes to a folder, it will by default be put in a namespace that reflects the folder hierarchy.

The classes will be easier to find and that alone should be reasons good enough.

The rules we follow are:

• Project/assembly name is the same as the root namespace, except for the .dll ending
• Only exception to the above rule is a project with a .Core ending, the .Core is stripped off
• Folders equals namespaces
• One type per file (class, struct, enum, delegate, etc.) makes it easy to find the right file

Answer 3

I think the standard, within .NET, is to try to do it when possible, but not to create unnecessarily deep structures just to adhere to it as a hard rule. None of my projects follow the namespace == structure rule 100% of the time, sometimes its just cleaner/better to break out from such rules.

In Java you don't have a choice. I'd call that a classic case of what works in theory vs what works in practice.

Answer 4

@lassevk: I agree with these rules, and have one more to add.

When I have nested classes, I still split them out, one per file. Like this:

// ----- Foo.cs
partial class Foo
{
    // Foo implementation here
}

and

// ----- Foo.Bar.cs
partial class Foo
{
    class Bar
    {
        // Foo.Bar implementation here
    }
}

Answer 5

I'd say yes.

First, it will be easier to find the actual code files by following down the namespaces (say, when somebody e-mails you a naked exception call stack). If you let your folders go out of sync with namespaces, finding files in big codebases becomes getting tiring.

Second, VS will generate new classes you create in folders with the same namespace of its parent folder structure. If you decide to swim against this, it will be just one more plumbing job to do daily when adding new files.

Of course, this goes without saying that one should be conservative about how deep xis folder/namespace hierarchy goes.

Answer 6

Yes they should, only leads to confusion otherwise.

Answer 7

What's the standard?

There is no official standard but conventionally the folder-to-namespace mapping pattern is most widely used.

In class libraries do the folders usually match the namespace structure or is it a mixed bag?

Yes, in most class libraries the folders match the namespace for organizational ease.