Spurred by some of the recent discussion threads, I started writing
the below. But then I stopped: don't we already have something like
the below already, in several places, and that hasn't helped much...
I have little idea where to put this, if anywhere.
--- cut here ---
First and foremost: you are naming your module so that people
can find your module. It's as easy - and as difficult - as that.
Suggest two-level namespaces only. You can use deeper namespaces
than that internally in your module, of course, but for namespace
registration, only speak in two level namespaces.
If you are thinking of introducing a new top-level namespace,
think carefully. Does your module really not fit under any
existing category? Suggesting new top-level namespaces is
likely to be met with great suspicion.
Even though the module naming is in practice a first-come
first-served process, it is quite impolite to grab top-level
names. Yes, even if your project/product is named with
just a single word, please think of people trying to find
something that would help them in their problems. Unless
they know of your project/product, they might not ever find
your module.
Use as specific descriptive nouns, and even preferably, verbs, as
possible as the components of your names. Describe the function,
not the implementation. Avoid vague or generic words.
Stay away from qualitative (advertising) adjectives like "Fast" or
"Small", or even worse, "Super", "Hyper" and its kind. All these are
relative virtues, and as modules develop and new modules are
introduced, also volatile and transient virtues. You are hoping that
other programmers would use your module, and they are as suspicious
and weary of hypewords as you are.
Do not embed the implementation or interface of the module to your
module name (Foo::XS, Foo::OO). The user shouldn't care. Instead,
make your module clever enough to choose dynamically between
implementations and interfaces.
We have unfortunately quite many "Object" or "OO", "XS"
or "PL", and "Tk" or "Gtk" examples.
Co-operate. If your module would work as a patch to an existing
module, contact the author of that module and suggest this
possibility. Be polite. Document your changes carefully
and supply good tests. Also, this way you can get someone else
maintaining your code.
If you are thinking of a funny cutesy ha-ha name, please reconsider.
Trust us, the joke will feel much less funny in a month. Note that
there is nothing wrong with recreational programming, and if you want
to show off some sort of clever trick, please use the "Acme::"
top-level hierarchy.
Do try to stay away from acronyms unless they are really widely
known (standards or de facto standards, like HTML). Unless people
are familiar with your acronym, they will never look at your module.
If you are thinking of a module name containing a trademark,
please don't, unless you are working for the owner of the trademark.
You don't like getting phone calls from lawyers, neither do we.
Trademark owners do have priority over deciding what
gets published under categories named after the trademarks.
If you were a company owning the trademark FooWare, wouldn't
you have an interest in someone unrelated you releasing
FooWare::Ping? The FooWare::Ping might be either unrelated
to your FooWare, or related but a really badly written module,
or simply you do no want anyone thinking your company is
responsible for the module, or someone might be trying
to make a joke out of trademark.
Yes, this had happened.
You don't work for the owner of the trademark but you got
a verbal okay from some in the company? Sorry, that's not
enough. Get it in writing from their lawyers, get the writing
checked by a lawyer familiar with trademarking issues.
You work for a company and you are thinking of releasing a module
somehow related to your company's product? That's excellent, but
please check with your manager, and preferably with your lawyers.
Are you really supposed to release that software publicly?
We have had this happening: someone working for a company
released a module he wasn't suppposed to, and then left
the company. The company did learn of this and got
a little bit huffy-- but luckily in this case the person
was found, and they settled amicably.
Top-level names to stay away from: Devel, Sys, Text, unicore,
names all in lowercase.
Devel is mainly meant for modules to do with
low-level debugging of/inside Perl itself.
It does not stand for "development" or "developer"
in general.
Sys is a complete disaster. Adding Sys:: in front
of something is completely redundant. We are sorry
it ever got used. Yes, we know there's Sys::Syslog
in the core, and we are we ashamed because of it.
Text is most often very low in information, too.
If your module is working with a natural language
or languages, use "Lingua::". "Text::" is fine
if your module is dealing with formatting of text,
for example. If you are thinking of using "Text"
because your interface is in text, please don't.
Unicore/unicore is reserved for the use of the Perl
core for Unicode things.
All lowercase names are reserved for the use of
the core Perl language.
--
$jhi++; # http://www.iki.fi/jhi/
# There is this special biologist word we use for 'stable'.
# It is 'dead'. -- Jack Cohen
