Axiom Namespaces: A Visit to FlatLand

[Terry L. Triplett]

I put on my architect's hat the other day and imported Axiom into my
design tool, ostensibly to wrap my brain around Axiom's architecture,
but also to start thinking about things like API documentation, high
level user documentation and such. I was a little surprised to find
that despite the impression given by the filesystem layout under
"Axiom/Engine", the logical structure of the class hierarchy is
practically flat. With a few exceptions, almost everything resides in
the "Axiom" namespace, resulting in a huge, unmanageable and impossibly
complex diagram.

Now granted, I'm at a slight disadvantage here because I'm not fully
conversant with the Microsoft .NET Framework Design Guidelines and my
sensibilities are influenced by the "bondage and discipline" approach to
design required by Java packages, but this doesn't strike me as an
example of "best practices".

I'd like to do some refactoring and work the logical structure of the
code into something a little more sane. The organization suggested by
the filesystem layout seems like a good starting point, since it makes
sense (with the exception of "Engine" which is redundant). This could
probably be taken further, as suggested by the concepts discussed here:
http://www.developer.com/design/article.php/3573356, but that requires
more thought and work.

What say the .NET Design experts in the house?

[Serge Lobko-Lobanovsky aka arilou]

Hello Terry,

You seems to somehow have missed the discussion about namespaces in
Axiom. I gather Borrillis decided to make it lean in favor of Ogre
which also has a simple plain Ogre namespace.

However, to me it seems that some things CAN be moved to their own
namespaces.

--
Best regards,
Serge mailto:serge.lo...@gmail.com

[Terry L. Triplett]

Actually I read through a few long threads in the archives yesterday,
but didn't find anything to stop me from making my post (though I do
like "ORCA" - we should use that). I could have missed whatever you are
referring to.

This is a highly debatable issue, of course, especially since .NET makes
organization by package/namespace more of an option than a mandate like
Java. But from a OO design perspective, sensible higher order
organization of the codebase is just as valuable as it is at the class
level. Cramming everything into a single namespace makes as much sense
to me as putting all the logic in a class into main() or the
constructor. IMHO. :-)

[Michael Cummings]

I did flatten it on purpose, looking at applications that used Axiom. Typically in order to create an application that used most of the feature ( and this even included the main Axiom classes themselves) you would typically have 4-10 using statements at the top of ever file. I realize that this makes it seem like a big unmanageble mess, but I have found it much easier to work with since it was flattened. I have less junk at the top of all of my files, and I am not encumbered to remember whether the class I am using is in Core or Animating or whatever other namespace is there.

 

I don't mind revisiting thihs, but it is going to take some real good arguments to convince me that having more namespaces is good.

 

[Michael Cummings]

Case in point, look at how MDX is organized in 2.0, one assembly, 3 main namespaces.

 

Microsoft.DirectX

Microsoft.DirectX.Direct3D

Microsoft.DirectX.DirectInput

 

 

With most of the classes used in Direct3D namspace.

 

[Serge Lobko-Lobanovsky aka arilou]

Borrillis,

I'd suggest that we move stuff that is not core to separate namespaces. Among them:

Axiom.Vfs

Axiom.Plguins

Because you are not going to include them unless you'll be playing with Vfs extenders and plugin implementations. 

[Terry L. Triplett]

Citing a concrete example of poor design as an argument doesn't change
the fact that it's poor design. :-)

Michael Cummings wrote:

> Case in point, look at how MDX is organized in 2.0, one assembly, 3
> main namespaces.
>
> Microsoft.DirectX
> Microsoft.DirectX.Direct3D
> Microsoft.DirectX.DirectInput
>
>
> With most of the classes used in Direct3D namspace.
>
>

> On 2/8/06, *Michael Cummings* <cummings...@gmail.com

> <mailto:cummings...@gmail.com>> wrote:
>
> I did flatten it on purpose, looking at applications that used
> Axiom. Typically in order to create an application that used most
> of the feature ( and this even included the main Axiom classes
> themselves) you would typically have 4-10 using statements at the
> top of ever file. I realize that this makes it seem like a big
> unmanageble mess, but I have found it much easier to work with
> since it was flattened. I have less junk at the top of all of my
> files, and I am not encumbered to remember whether the class I am
> using is in Core or Animating or whatever other namespace is there.
>
> I don't mind revisiting thihs, but it is going to take some real
> good arguments to convince me that having more namespaces is good.
>
>

> On 2/8/06, *Serge Lobko-Lobanovsky aka arilou* <
> serge.lo...@gmail.com <mailto:serge.lo...@gmail.com>>

> wrote:
>
>
> Hello Terry,
>
> You seems to somehow have missed the discussion about
> namespaces in
> Axiom. I gather Borrillis decided to make it lean in favor of
> Ogre
> which also has a simple plain Ogre namespace.
>
> However, to me it seems that some things CAN be moved to their own
> namespaces.
>
> --
> Best regards,
> Serge mailto:

> serge.lo...@gmail.com <mailto:serge.lo...@gmail.com>
>
>
>

[Serge Lobko-Lobanovsky aka arilou]

LMAO :)

Wednesday, February 8, 2006, 6:21:11 PM, you wrote:

> Citing a concrete example of poor design as an argument doesn't change
> the fact that it's poor design. :-)

--

[Terry L. Triplett]

Read the discussion at the link I posted. They address the issues
involved pretty well - most of what I would say follows that logic.

Basically I'd say there is a tension between 2 different roles at work
here: the developer of the library and the user of the library. The
arguments you give make sense - as a developer you want convenience and
efficiency. Your arguments all arise from the desire to streamline the
developer experience. To the user of the library trying to make sense
of the codebase, those development-time conveniences aren't a big help -
the goal is different. The arguments for adding some (note I said
*some*, not extreme) structure to the namespace hierarchy are driven by
the same kinds of goals that drive things like naming conventions,
comments, regions and such when designing classes: readability and
comprehension.

Michael Cummings wrote:

> I did flatten it on purpose, looking at applications that used Axiom.
> Typically in order to create an application that used most of the
> feature ( and this even included the main Axiom classes themselves)
> you would typically have 4-10 using statements at the top of ever
> file. I realize that this makes it seem like a big unmanageble mess,
> but I have found it much easier to work with since it was flattened. I
> have less junk at the top of all of my files, and I am not encumbered
> to remember whether the class I am using is in Core or Animating or
> whatever other namespace is there.
>
> I don't mind revisiting thihs, but it is going to take some real good
> arguments to convince me that having more namespaces is good.
>
>

> On 2/8/06, *Serge Lobko-Lobanovsky aka arilou*

> <serge.lo...@gmail.com <mailto:serge.lo...@gmail.com>> wrote:
>
>
> Hello Terry,
>
> You seems to somehow have missed the discussion about namespaces in
> Axiom. I gather Borrillis decided to make it lean in favor of Ogre
> which also has a simple plain Ogre namespace.
>
> However, to me it seems that some things CAN be moved to their own
> namespaces.
>
> --
> Best regards,
> Serge mailto:

> serge.lo...@gmail.com <mailto:serge.lo...@gmail.com>
>
>

[JW Sullivan]

Namespaces are really more of an organizational concept than a design concept.  The question here is does splitting up the classes into separate organizations really help.  It is often the case that splitting things into separate namespaces just makes it more difficult.

 

I think that arilou's suggestion is probably the best and most common reason to add the extra namespaces.  All of the classes required to use the project can be placed in some core namespace (eg. Axiom), then the classes that you would only need to use if you are creating a plugin, or overriding some feature can be placed in a different namespace (eg Axiom.Plugins).

 

J.W.

[Terry L. Triplett]

I meant that in the nicest of ways, of course. Might as well have a
little fun. :-)

Interesting aside: I was looking up some information on "Effective C#"
by Bill Wagner - I've always found Scott Meyer's books to be invaluable
references (eg. Effective C++) - and it turns out the author lives right
here in Ann Arbor. And I just missed a talk by him last week for the
local .NET developer's group. Damn. I might have to look him up and
pick his brain - seems like a good resource to have living in the same town.

Serge Lobko-Lobanovsky aka arilou wrote:

[Serge Lobko-Lobanovsky aka arilou]

Terry,

It seems to me you are mismatching the roles - from the "user of the
library" experience, having to browse thru the codebase to find the
namespace that should be included is not friendly, isn't it?

Wednesday, February 8, 2006, 6:39:13 PM, you wrote:

> Read the discussion at the link I posted. They address the issues
> involved pretty well - most of what I would say follows that logic.

> Basically I'd say there is a tension between 2 different roles at work
> here: the developer of the library and the user of the library. The
> arguments you give make sense - as a developer you want convenience and
> efficiency. Your arguments all arise from the desire to streamline the
> developer experience. To the user of the library trying to make sense
> of the codebase, those development-time conveniences aren't a big help -
> the goal is different. The arguments for adding some (note I said
> *some*, not extreme) structure to the namespace hierarchy are driven by
> the same kinds of goals that drive things like naming conventions,
> comments, regions and such when designing classes: readability and
> comprehension.

--

[Terry L. Triplett]

JW Sullivan wrote:

> Namespaces are really more of an organizational concept than a design
> concept.

I'm not quite sure there's a distinct difference. I'd say organization
is a subset of the factors one considers when designing.

> The question here is does splitting up the classes into separate
> organizations really help. It is often the case that splitting things
> into separate namespaces just makes it more difficult.

Other than impacting convenience while coding, what difficulties do
namespaces introduce, exactly?

>

[Michael Cummings]

Terry, from your article reference:

 

AVOID having too many namespaces.

Users of a framework should not have to import many namespaces in most common scenarios. Types that are used together in common scenarios should reside in a single namespace if at all possible.

:)

 

I don't mind moving some things that aren't used by normal developers into seperate namespaces as arilou suggests, but I want to make sure that we don't end up with too many again.

 

[Michael Cummings]

Again from the article reference:

 

JEFFREY RICHTER As an example of a problem, the runtime serializer types are defined under the System.Runtime.Serialization namespace and its subnamespaces. However, the Serializable and NonSerialized attributes are incorrectly defined in the System namespace. Because these types are not in the same namespace, developers don't realize that they are closely related. In fact, I have run into many developers who apply the Serializable attribute to a class that they are serializing with the System.Xml.Serialization's XmlSerializer type. However, the XmlSerializer completely ignores the Serializable attribute; applying the attribute gives no value and just bloats your assembly's metadata.

Incorrectly applying namespaces could result in senarios like the above.

 

On 2/8/06, Terry L. Triplett <te...@triplett.org> wrote:

[Michael Cummings]

BTW, nice article.

:)

 

On 2/8/06, Michael Cummings <cummings...@gmail.com> wrote:

[JW Sullivan]

This is a good discussion to have.  One thing to remember is that the user of an API is also a developer.  They care just as much about convenience and efficiency as the developer of the API.  The article you linked to does have some good guidelines for how to deal with namespaces.  One of them stated that you should avoid creating too many namespaces, and I think that Axiom originally had too many namespaces.  The organization of those namespaces made sense, but it was hard to remember which namespace you needed for certain classes.  That was the motivation behind going to the current flat structure.  This may be an area to revisit as Michael stated, and if a better way of organizing things can be proposed, then it may be worth reorganizing again.

 

J.W.

[Terry L. Triplett]

Bad analogy, but:

Go to the library to find a book about, uh, Labrador Retrievers.

Library A has *all* their books in alphabetical order by title. No
other form of organization. This is the analogy to a single flat
namespace. Try to find all the books about dogs. Try to find all the
books about Labrador Retrievers. Try to find all the books by Stephen
King, for that matter.

Library B organizes their books the way we are normally used to:
grouped by subject, author, etc. Find all the books about dogs. There
they are, all together, grouped by subject. Find all the books about
Labrador Retrievers. There they are, all in a group. Look for Stephen
King books. There they are, all in a group.

Which library will get you the book you want faster? Which is more
friendly to the user?

It may be "just organization", but as the number and variety of things
you organize goes up, the value of organization increases.

My IDE says there are 453 classes in the Axiom/Engine directory tree.
Find all the classes related to Particle Systems. Find all the
Filesystem classes. Find all the Animation classes. You can't use the
filesystem layout - that's cheating. Use the logical structure of the
class hierarchy only.

Another way to pose my question is: why is it valuable to organize the
*physical* structure of the code (filesystem layout), but not the
logical structure of the code? Based on the arguments I'm seeing, most
of the files in Axiom/Engine should all be dumped into the same
directory. Why isn't that the case? Because there is some value to the
organization, is my answer.

Serge Lobko-Lobanovsky aka arilou wrote:

[Terry L. Triplett]

Damn, I'm starting to get lost in all of these posts. Now I understand
the story of Pandora's box better. :-)

That's a very important point, and one not lost on me. That's why the
language-as-bondage-master model used by Java feels uncomfortable, and
why C# "feels" better to me. This is the basis of the tension between
two different use cases I mentioned. Very much like coupling/cohesion
in OO design - too much of either is just as useless, and finding the
proper balance is an art, and varies by situation, no less. Are we
having fun yet? :-)

Note I didn't ask for the utmost in granular namespaces, just the
possibility of organizing one big-a$$ namespace in a slightly more
sensible way.

Michael Cummings wrote:

> Terry, from your article reference:
>
>

> *AVOID* having too many namespaces.

>
> Users of a framework should not have to import many namespaces in most
> common scenarios. Types that are used together in common scenarios
> should reside in a single namespace if at all possible.
>
> :)
>
> I don't mind moving some things that aren't used by normal developers
> into seperate namespaces as arilou suggests, but I want to make sure
> that we don't end up with too many again.
>
>

> On 2/8/06, *Terry L. Triplett* <te...@triplett.org

[Michael Cummings]

in a slightly more sensible way.

Now, how about some ideas?

 

• Axiom
• Plugins
• RenderSystems
• PlatformManagers
• SceneManagers

Anything Else. I am considering moving the 'support classes' for the RenderSystems, PlatformMangers and SceneMangers under those respective namespaces.

 

We need a whiteboard :)

 

On 2/8/06, Terry L. Triplett <te...@triplett.org> wrote:

[Terry L. Triplett]

So the current layout of the filesystem is what was considered excessive?

Michael Cummings wrote:

> in a slightly more sensible way.
> Now, how about some ideas?
>
>

> * Axiom
> o Plugins
> o RenderSystems
> o PlatformManagers
> o SceneManagers

[Michael Cummings]

Yeap.

On 2/8/06, Terry L. Triplett <te...@triplett.org> wrote:

[Terry L. Triplett]

Michael Cummings wrote:

> in a slightly more sensible way.
> Now, how about some ideas?
>
>

> * Axiom
> o Plugins
> o RenderSystems
> o PlatformManagers

> o SceneManagers

>
> Anything Else. I am considering moving the 'support classes' for the
> RenderSystems, PlatformMangers and SceneMangers under those respective
> namespaces.
>
>

Working on it, since I started this. I've wasted too much time today
writing emails, so I'll chime in when I have something to say.

[Rob Loach]

The namespace system that Michael proposed sounds effective.

[Terry L. Triplett]

I agree, though Platform, Rendersystem and Scenemanager namespaces
already exist, so don't really affect the root Axiom namespace much.

This seemed like a good opportunity for an exercise in analysis - I'm
always open for a chance to refine my approaches and techniques. So I
went out and bought the Cwalina/Abrams Framework Design Guidelines book
(cited in the article) and am reading through it now. The plan is to
analyze the codebase with tools like NDepend, .NET Reflector, FxCop and
the like to understand the organization and relationships of the class
model, apply the above-mentioned design guidelines and report back here
with some *informed* suggestions. This will likely take awhile - as
they say in the first chapter of the book "Well-Designed Frameworks are
expensive to design. ... It is hard work that consumes lots of time and
resources."