From: Trans <transfire@...>
Date: 2008-04-12T00:28:27+09:00
Subject: Designing Namespaces

I find it curious that whenever I design an application and begin to
organize the class/module namespaces, I get something like:

  module FooMusic

    class Instruments::WindInstruments::Trumpet < WindInstrument

    class Instruments::WindInstruments::Clarinet < WindInstrument

    class Instruments::StringInstruments::Violin < StringInstrument

Which seems very nice for explicitness, But then, of course, I think
it's way too wordy. So I'll scale it back to something, that doesn't
read as nice, but is nonetheless more concise.

  module FooMusic

    class Instruments::Winds::Trumpet < WindInstrument

    class Instruments::Winds::Clarinet < WindInstrument

    class Instruments::Strings::Violin < StringInstrument

But then I start to think, what does all this hierarchy matter? Is
anyone ever going to 'include Instruments'? I call YAGNI on myself.
Save some bytes and typing and end up with:

  module FooMusic

    class Trumpet < WindInstrument

    class Clarinet < WindInstrument

    class Violin < StringInstrument

And honestly I'm pretty happy with that, except.... Have classes other
than instruments in the app, say Musician and Orchestra, then I run
into two sore spots:

1) If file names reflect module/class, then file organization gets
messy. Eg.

  foomusic/clarinet
  foomusic/musician
  foomusic/orchestra
  foomusic/trumpet
  foomusic/violin

So I tend to want to organize the actual files according to category
(as in the earlier module organization):

  foomusic/instruments/wind/trumpet
  foomusic/instruments/wind/clarinet
  foomusic/instruments/string/violin
  foomusic/players/musician
  foomusic/players/orchestra

That's okay, I can live without that general correspondence between
namespace and file name. But...

2) The RDocs aren't sorted by subclass, so organization is messy there
too. And I feel much worse about this one because documentation is so
important. However, I keep telling myself "don't code to the docs".
Not sorting by subclass is a lack of RDocs, and not something I should
compensate for in my library design.

What are other people experiences with all this? Do you find it better
use highly categorized namespaces and to stick with namespace/filename
mapping? Or have you too found alternates organizations you prefer?

Thanks,
T.