Designing Namespaces

[Trans]

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.

 

[ara.t.howard]

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,

child classes should be inner classes - saves a ton of typing


class WindInstrument

class Trumpet < WindInstrument
end

class Carinet < WindInstrument
end

end


and then use shortcuts


def Music.trumpet *a, &b

if a.empty? and b.nil?

WindInstrument::Trumpet

else

WindInstrument::Trumpet.new *a, &b

end


trumpet = Music.trumpet(arg, arg){ block }


so the two main concepts are:

- nest classes under parent
- assign shortcuts

i'm not strict with that - but both are useful for maintaining
sanity. i esp like

children = Parent.constants.select{|c| Parent > Parent.const_get(c)}

not that code - but you get the idea

a @ http://codeforpeople.com/

 

[Robert Dober]

child classes should be inner classes - saves a ton of typing


class WindInstrument

class Trumpet < WindInstrument
end

class Carinet < WindInstrument
end

end


and then use shortcuts


def Music.trumpet *a, &b

if a.empty? and b.nil?

WindInstrument::Trumpet

else

WindInstrument::Trumpet.new *a, &b

end


trumpet = Music.trumpet(arg, arg){ block }


so the two main concepts are:

- nest classes under parent
- assign shortcuts

i'm not strict with that - but both are useful for maintaining sanity. i
esp like

children = Parent.constants.select{|c| Parent > Parent.const_get(c)}

not that code - but you get the idea

a @ http://codeforpeople.com/

Very interesting approach Ara, allow me to express some skepticism
about the shortcut delivering either the class or an instance of it.
The idea is sure enough brilliant as a solution to name pollution, I
wonder however if it is not a maintenance trap...
Now if it became a well known pattern this danger would go away. In
order to easier recognize the pattern I would suggest to use
Capitalized names for your shortcut/factory methods. How does that feel?

Cheers
Robert

 

[ara.t.howard]

Very interesting approach Ara, allow me to express some skepticism
about the shortcut delivering either the class or an instance of it.
The idea is sure enough brilliant as a solution to name pollution, I
wonder however if it is not a maintenance trap...
Now if it became a well known pattern this danger would go away. In
order to easier recognize the pattern I would suggest to use
Capitalized names for your shortcut/factory methods. How does that
feel?

i've gone back and forth a few times

Foo.Bar

throws my brain for a loop though, so i've tended toward

Alib.util.snakecase 'FooBar'

but i'm not religious about it...

cheers.

a @ http://codeforpeople.com/

 

[Marc Heiler]

And I feel much worse about this one because documentation is so important.

Yes documentation is important, especially about teaching other people,
or showing them how this is supposed to be used (and even better how it
is designed and why, if there is enough space and time to do so, in a
brief and concise manner) - but a documentation tool should not come
into one's way to think and design in my humble opinion. The current way
leaves some things to be desired with rdoc - one example I found
peculiar is that a .rb file of rake had about 6 methods. And ALL methods
had # :nodoc: assigned and exactly 0 lines of other docu. I think this
is somewhat sub-optimal as solution to think about documentation this
way, that the first line of thought is wrapped towards the tool rather
than other people (but just to get it out too, i think having rdoc is a
lot better than not having it)