Forum: Ruby What's the best practise in naming modules?

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
Ded98dc06a045924f0d48b2e46fdf229?d=identicon&s=25 Henrik Martensson (Guest)
on 2006-01-06 12:11
(Received via mailing list)
Hi,

I have a question about the best practise in naming Ruby modules.

I am working on a module for unit testing XML documents (and document
fragments). It would be logical, I think, to name the module
Test::Unit::XML, and to load it using "require 'test/unit/xml'".

However, this naming scheme could cause problems. For example, if the
core unit test package is extended with assertions for testing XML.
Also, even if my xml.rb file is physically separate from the files in
the core test/unit directory, I don't feel comfortable with the possible
overlap in names.

I could of course change the names:

XML::Test::Unit
require 'xml/test/unit'

or I could do something like this:

Test::Unit::XML
require 'testunitxml'

However, I neither of these alternatives is as appealing.

What is the recommended Ruby practise in these cases?

I plan to release the module, whatever its name, on RubyForge as soon as
the naming issue has been resolved.


/Henrik

--

http://www.henrikmartensson.org/  - Reflections on software development
5befe95e6648daec3dd5728cd36602d0?d=identicon&s=25 Robert Klemme (Guest)
on 2006-01-06 12:29
(Received via mailing list)
Henrik Martensson wrote:
> Also, even if my xml.rb file is physically separate from the files in
> Test::Unit::XML
> require 'testunitxml'
>
> However, I neither of these alternatives is as appealing.
>
> What is the recommended Ruby practise in these cases?
>
> I plan to release the module, whatever its name, on RubyForge as soon
> as the naming issue has been resolved.

Is this a general module for XML testing or is it a module for testing
specific XML?  In the former case I'd contact project maintainers of
Test::Unit and discuss with them whether and how to integrate your code
into Test::Unit.  In the latter case I would definitively avoid using
Test::Unit's namespace.  In that case you should use the namespace of
your
project along the lines of YourProject::Test::Xml or
YourProject::Test::XML.

HTH

    robert
A6d3a37b5badfdd2f47655aa0e46604e?d=identicon&s=25 Eivind Eklund (Guest)
on 2006-01-06 12:32
(Received via mailing list)
On 1/6/06, Henrik Martensson <henrik.martensson@bostream.nu> wrote:
> I could of course change the names:
>
> What is the recommended Ruby practise in these cases?

First of all, I'd coordinate this with Nathaniel (author of
Test::Unit, nathaniel@talbott.ws).

Second, I'd call it something complete different - a unique name,
totally off the Test::Unit namespace, until it has lived for a while
with different people using it.  If it seems like a good idea *then*,
I'd rename it into Test::Unit::XML (again, after coordinating with
Nathaniel).

The delay is to make sure that the design is sound, that you don't
find a better and incompatible way to test shortly after, and have
taken the main namespace.  That namespace should be for something
that's fairly permanent.

Eivind.
Ded98dc06a045924f0d48b2e46fdf229?d=identicon&s=25 Henrik Martensson (Guest)
on 2006-01-06 14:38
(Received via mailing list)
On Fri, 2006-01-06 at 12:31, Eivind Eklund wrote:

> First of all, I'd coordinate this with Nathaniel (author of
> Test::Unit, nathaniel@talbott.ws).

I mailed him, but it was only yesterday, so he hasn't had very much time
to reply yet.

As you may notice, I'm chomping at the bit. I have two other projects in
the pipeline that involve both Ruby and XML. They will all rely heavily
on the XML unit test framework.

I expect to have a lot of free time in which to bury myself in Ruby code
the next two, maybe three weeks. After that, the work will probably slow
down. This is important to me, since the projects I'm working on have
very definite deadlines.

>
> Second, I'd call it something complete different - a unique name,
> totally off the Test::Unit namespace, until it has lived for a while
> with different people using it.  If it seems like a good idea *then*,
> I'd rename it into Test::Unit::XML (again, after coordinating with
> Nathaniel).

Good advice.

>
> The delay is to make sure that the design is sound, that you don't
> find a better and incompatible way to test shortly after, and have
> taken the main namespace.  That namespace should be for something
> that's fairly permanent.

Also good advice. In this case, the API will be fairly stable though.
There is only one assertion, assert_xml_equal. The internals may change,
but the method signature won't. I will add more assertions eventually,
but only as the need (my own or other peoples) arise.

The main design decision has been whether to subclass TestCase, or just
mix XML assertions in. Since Test::Unit seems to favor mixins, that's
the approach I'm currently taking. (It is also one of the things I want
to discuss with Nathaniel before I inflict the module on the world.)

/Henrik

--

http://www.henrikmartensson.org/  - Reflections on software development
Ded98dc06a045924f0d48b2e46fdf229?d=identicon&s=25 Henrik Martensson (Guest)
on 2006-01-06 15:26
(Received via mailing list)
On Fri, 2006-01-06 at 12:28, Robert Klemme wrote:
<snip>
>
> Is this a general module for XML testing or is it a module for testing
> specific XML?  In the former case I'd contact project maintainers of
> Test::Unit and discuss with them whether and how to integrate your code
> into Test::Unit.  In the latter case I would definitively avoid using
> Test::Unit's namespace.  In that case you should use the namespace of your
> project along the lines of YourProject::Test::Xml or
> YourProject::Test::XML.

It is a generic framework. The goal is to write something along the
lines of the XMLUnit extension to JUnit, but of course adapted to fit
with Test::Unit and Ruby style programming. I am taking a minimalistic
approach, and aim to follow the "release early, release often" mantra.

The first version is extremely simple, with only an assert_xml_equal
assertion. Namespaces are handled correctly, and extraneous whitespace
is ignored for comparison purposes. There is as yet no support for
comparing doctypes and entity declarations, or for validating documents.
Nor is there any support for comparing structures while ignoring content
and attributes, yet. Still, as it is right now, I believe I have covered
the most common situations where you want to test well formed XML.

One of the things I like very much about Ruby is the refreshing absence
of XML configuration files. This is probably why no one has written an
XML unit test framework yet. (At least, I haven't found one.) Still, XML
tends to creep in just about everywhere. I hope more people than I will
find the framework useful.


/Henrik

--

http://www.henrikmartensson.org/  - Reflections on software development
This topic is locked and can not be replied to.