The project I’m working on has quite a few classes. These classes can be grouped in two different ways. I’m trying to decide which grouping is best as for namespacing. Currently I a set of user facing classes that look like:
JamJarHoneyJarPeanutButterJar- etc…
These are all similar in that they all inherit from SpreadableJar, each spreadable prefix could be considered a ‘topic’ within in the project.
I also have a set of objects relating to these topics, each topic usually has a set of constant definitions and message classes associated with it so I end up with a bundle of files such as:
JamDefinitionsPeanutButterSpreadMessageHoneyDefinitionsJamRemoveMessage- etc…
I can think of two ways to organise these files:
-
By Topic
First level is namespace, second is class/file name.- Jam
- Jar
- Definitions
- RemoveMessage
- etc…
- Honey
- Jar
- Definitions
- etc…
- PeanutButter
- Jar
- Definitions
- SpreadMessage
- etc…
- Jam
This seems tidy (removes duplicated names) and is useful to the user of the library but means that all the Jar files look the same in the project structure, and each Jar class no longer has a descriptive name. It also means that related objects are grouped together so they will not need to scope into each others namespaces
-
By Purpose
- Jars
- JamJar
- HoneyJar
- PeanutButterJar
- Definitions
- JamDefinitions
- HoneyDefinitions
- PeanutButterDefinitions
- Messages
- JamRemoveMessage
- etc…
- Jars
This way is clear to the user if they know that they need to use Jars (the rest of the objects won’t be needed by external users) and it separates the large number of messages and the separate definitions files from the main functionality, but now the Jars will need to scope into the other namespaces for their own definitions and messages and the file naming becomes more awkward. The ‘Jar’ from JamJar can’t really be removed because the class is not just ‘Jam’.
What is the best approach here? Am I missing some obvious solution or error in my structure?
2
Which of the two is more likely:
- Somebody is working with a jam jar, and while doing so, they want to look at a jam definition
- Somebody is working with a jam jar, and while doing so, they want to look at a honey jar?
You’re best placed to answer this, given your knowledge of the project, but in general I would say that the first of these two seems far more common. When working on jam-related functionality, your work may well span several interdependent classes. It seems much less likely that you’re going to want to work on a lot of classes for unrelated functionality/features just because the purpose they serve is similar (though it may occasionally come up, e.g. when dealing with cross-cutting concerns).
Given this, I’d say the top level namespace should be topic, allowing easy grouping of related code.
As for:
(removes duplicated names) … but means that all the Jar files look the same in the project structure, and each Jar class no longer has a descriptive name.
This is a trade-off you’re choosing to inflict on yourself. There’s nothing stopping you from having Jam.JamJar, for example.
While I can see the argument for not wanting to duplicate names like that, overall removing the Jam part from the name seems like a poor trade-off. It doesn’t play well with namespace imports/usings at all. If you import a single namespace, your classes end up with less descriptive names. If you import multiple namespaces, you end up with ambiguities which are annoying to resolve.
You could perhaps import the base namespace then do Jam.Jar, etc., but this is atypical, people won’t really be used to doing it, and you may suddenly find yourself writing a new class that doesn’t fit well into this more rigid naming scheme.