What's the best practise in naming modules?

[Henrik Martensson]

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

 

[Robert Klemme]

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.

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

 

[Eivind Eklund]

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?

First of all, I'd coordinate this with Nathaniel (author of
Test::Unit, (e-mail address removed)).

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.

 

[Henrik Martensson]

First of all, I'd coordinate this with Nathaniel (author of
Test::Unit, (e-mail address removed)).

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

 

[Henrik Martensson]

On Fri, 2006-01-06 at 12:28, Robert Klemme wrote:

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