in reply to A First CPAN Odyssey

SK> a module for abstracting objects and relationships in a SQL database

JZ> Sorry to be pedantic, but you are asking about namespace so I'll get picky - there is no such thing as a "SQL database" - there are database management systems which use the SQL language to interact with data.

SK> The first thing I'm wondering about is name spacing issues.

JZ> You should cc these questions to dbi-dev@perl.org, that is the definitive place for DBI related namespace issues.

SK> Presently, the top level package name is just SQL, so I have sub-packages such as SQL::Object, SQL::Link, SQL::Statement, SQL::Object::ResultSet, SQL::Link::ResultSet, etc.

JZ> Several of those are already taken

SK> I realize that this probably isn't a very good name, but I'm not sure what would be. The SQL name is nice and short, but not really all that descriptive of what the module is doing.

JZ> As the author/maintainer of several CPAN modules in the SQL namespace (though this of course gives me no more rights to comment than anyone else), I would strongly prefer that the namespace be for modules whose primary purpose is dealing with the SQL language. Modules whose primary purpose is dealing with Databases or with Data or with DBI belong elsewhere.

SK> What would be a sensible name?

JZ> To answer that, we need to know what your module does. A decription like you provide "a module for abstracting objects and relationships in a SQL database" is so general that it's hard to comment. I suggest you come up with three different descriptions of your module - a 40 character one for use in the module list, a two sentence one for general descriptions like this posting, and a one page one for a README. Look through other CPAN modules and make sure that each of your descriptions not only describes what your module does, but does that in a way that distinguishes it from other modules. Post them back here, and I'll be glad to comment further. Good luck!

Replies are listed 'Best First'.
Re^2: A First CPAN Odyssey
by skyknight (Hermit) on Jun 22, 2004 at 20:20 UTC

    At present, this is the top level POD I have that describes the module as a whole in an attempt to give a broad view of its purpose and organization. Then there is POD within each class that describes its usage which is not posted here.

    As someone else suggested, it would probably be best for me to simply move the top level name to some new unique name, so as to avoid collision with pre-existing things such as SQL::Statement.

    Oh, and please don't hesitate to be pedantic and highly critical. Submitting my first CPAN module stems not just from the desire to contribute something useful, but also from selfish motivations to learn the process of doing so. You are explicitly authorized to pull no punches. :-)

    Read more... (6 kB)
[reply]
      You should defintiely read simonm's great node - DBI Wrapper Feature Comparison and figure out how your module relates to the discussion there.

      It seems to me that your module uses SQL to accomplish things but *users* of your module will not be dealing with SQL at all. So therefore you should name the module something more related to what the users will be doing - using objects, persistence, relationships, etc. Take for example your SQL::Column - how is that at all related to SQL? You are providing information about the structure of the table not about the structure of a SQL statement.

      I think your module belongs in the DBIx:: namespace since it is primarily an alternate programming interface to DBI. I'm afraid I don't get any sense from your POD of how your module differs from the dozens of other similar modules (some of which don't do any better of a job at distinguishing themselves in their PODs). Why would someone want to use your module rather than one of the others? I am not at all saying this to discourage you from CPANing your module, rather suggeting you get as good a sense as you can of how a potential user would react to your description of the module - the more you can define what your module does that is unique and helpful and usable, the better the chance that a potential user will look at it. The more you have a defined sense of how your module is unique, the easier it will be to pick a name for it.

[reply]

        This is an excellent point... DBIx does seem like a much more logical home for this module. Indeed SQL is merely a component of the underlying engine, not something with which the user has much interaction, apart from writing conditions for object lookups. SQL::Column, for example, should become something like DBIx::Foo::Table::Column, where Foo is whatever I end up naming my module.

        Your point about the need to distinguish my module from the myriad others is also well taken. In retrospect, while I think my module's implementation and interfaces are quite good, you are dead on in saying that I've done a poor job selling its uniqueness. I shall take this to heart in the next revision. It doesn't matter how great my module is if people don't take the time to explore its capabilities.

[reply]

In Section Meditations