C# namespace and class naming convention for libraries

Question

I'm building libraries with various small utility functions in C#, and trying to decide on a namespace and class naming convention. My current organization is like this:

Company
Company.TextUtils
    public class TextUtils {...}
Company.MathsUtils
    public class MathsUtils {...}
    public class ArbitraryPrecisionNumber {...}
    public class MathsNotation {...}
Company.SIUnits
    public enum SISuffixes {...}
    public class SIUnits {...}

Is this a good way to organize the namespace and classes, or is there a better way? In particular it seems like having the same name in the namespace and class name (e.g. Company.TextUtils namespace and TextUtils class) is just duplication and suggests that the scheme could be better.

Answer 1

It's very difficult to determine how effective your naming strategy is in isolation from the rest of your code.

The namespace should give some idea where it fits in the broad structure of your codebase, and the class name would usually describe what sort of functionality or concept it represents within that area.

Caveats aside, in your specific example, if you're likely to have a lot more 'Util' type classes, I would consider putting them under Company.Utils.Maths etc. That way if you need to add functionality that's common to multiple utility areas, you already have a natural location for it.

Answer 2

There is a nice document that contains a lot of rules that you should follow to be in line with Microsoft: Framework Design Guidelines.

One thing that you should change: Do not name classes as their namespace. That will lead to compiler mixups. Just don't. Find a better name for either the class of the namespace.

Answer 3

It's been a while since I've worked with C# or the .NET ecosystem so I can't say what the current recommended best practices are. I'd recommend a change to your names like this:

Company
Company.Text
    public class TextUtils {...}
Company.Math
    public class MathUtils {...}
    public class ArbitraryPrecisionNumber {...}
    public class MathsNotation {...}
Company.SI
    public enum SISuffixes {...}
    public class SIUnits {...}

What I've done here is remove "Utils" from the namespace names. I think that "Util" should not be in a namespace, because the Company.Text namespace could one day contain classes that are not text utility classes. The Company.Math namespace already contains ArbitraryPrecisionNumber which Does not seem to be a "utility".

Removing "Util" from the namespace also clears up any confusion that might arise by having two things with the same name (as mentioned in Robert's answer: https://softwareengineering.stackexchange.com/a/340440/13156 )

Another way you could have organized the code:

Company
Company.Util
    public class TextUtils {...}
    public class MathUtils {...}
Company.Math
    public class ArbitraryPrecisionNumber {...}
    public class MathsNotation {...}
Company.SI
    public enum SISuffixes {...}
    public class SIUnits {...}

In this case, all of the utility classes reside in the same namespace. There is no more Company.Text namespace since the only thing there was a utility class.

Personally, I find the first option a bit more clear.

Answer 4

Using the same name for the namespace and the class inside it is problematic.

• If the namespace contains more than one class, why would other classes be put there? it doesn't feel right, because the goal of the name of the namespace is to describe all the classes within it, not just one. For instance, if you have JsonSerialization, BinarySerialization and XmlSerialization classes in a namespace, would it make sense to name your namespace XmlSerialization?

  What usually happens is that due to an extraction of a class from an existent namespace, or a merge between multiple classes or other reorganization, you find yourself with a namespace containing a major class; progressively, minor classes are put there because they are slightly related to the original class. For instance, a namespace LogParser may contain a single class LogParser, and then somebody puts LogConverter, because it's quite related to the parser, then LogSearcher, etc. The problem here is that the name of the namespace wasn't changed: as soon as LogConverter was added, the name should have been changed to LogsProcessing or, simply, Logs.

• If the namespace contains only one class, it might be a sign of an issue within the code organization.

  While I've seen a few times the situations where a single class with proper SOLID principles was very different from anything else in the code base and was therefore put in a dedicated namespace, such cases are rare. More often, this is indicative of a problem. Similarly, nothing prevents you from having a class containing a single method, but more often than not, such classes would indicate a problem.

  Even if your namespace contains only one class, there is usually a way to be more specific when naming the class, and more general when naming the namespace. Imagine an application which, among other things, should at a given moment convert files written in ABC format to DEF format. The conversion doesn't require any deserialization/serialization to/from the business objects, and is done by applying a bunch of regular expressions which are short enough to be put within the conversion class itself called AbcToDefConverter. All the conversion logic takes about 80 LLOC in about ten interdependent methods—seems like a situation where there is absolutely no need neither to split the existent class, nor create additional classes. Since the remaining part of the application has nothing to do with conversions, the class cannot be grouped with other classes in existent namespaces. So one creates a namespace called AbcToDefConverter. While there is nothing inherently wrong in that, one could also use a more generic name, such as Converters. In languages such as Python, where shorter names are preferred and repetition is thrown upon, it may even become converters.Abc_To_Def.

Therefore, do use different names for namespaces than for the classes they contain. The name of a class should indicate what the class is doing, while the name of the namespace should highlight what's common in all the classes put within it.

---

By the way, utility classes are wrong by nature: instead of containing something specific, such as arbitrary precision arithmetic, they rather contain everything which hasn't found its way in other classes. This is simply bad naming, just as a Miscellaneous directory on a desktop—something which is indicative of the lack of organization.

Naming exists for a reason: to make your life easier when you need to find stuff later. You know that if you need to draw a chart, you may try to search for “chart” or “plot”. When you need to change the way an app generates invoices, you'll search for “invoic[e/ing]” or “bill”. Similarly, try to imagine a case where you'll say to yourself: “hm, this feature should probably be found in misc”. I can't.

Look at .NET Framework. Aren't most of those classes utility classes? I mean, they have few things to do with the business domain. If I work on a financial app, or an e-commerce website, or the next gen education platform, serializing XML or reading files or doing SQL queries or performing transactions is all utility stuff. However, they are not called UtilitySerialization or UtilityTransaction, and they are not in the Utility namespace. They have proper names, which make it possible (and easy, thanks .NET developers!) to find them when I need them.

The same comes for your classes you commonly reuse in your apps. They are not utility classes. They are classes which do certain things, and the things they do should actually be the names of the classes.

Imagine you created some code which deals with units and conversion of units. You may name it Utility and be hated by your colleagues; or you may name it Units and UnitsConversion.