Choose a good module name.

First and foremost: you are naming your module so that people can find your module. It's as easy--and as difficult--as that.

Naming your Perl packages well is one of the most important things you can do. Choose a good name and people will naturally find it on CPAN. Choose a bad name, and your otherwise excellent code might never get a download. Imagine your module going out to CPAN one day. Will people look at your module name and instantly know what your module does? Will its name fit in with everything else that's already on CPAN.

There isn't a set of formal rules, or even its less restrictive little brother, guidelines, for naming your packages. Your module can use any name that it likes, but like all names, a good one goes a long way.

The modules@perl.org (the mailing list for PAUSE admins) and module-authors@perl.org can help you choose a good name. Not only are they generally good at names, but they also know quite a bit about what is already on CPAN. They can help you choose a name that puts your module into the right place with all of the other modules.

A module name must accomplish quite a bit in a few characters, and, once chosen, you rarely have the opportunity to change it after people start using it. The name of the module isn't for you; you don't need a name because you created it and understand it. The name is for other people, and those other people don't have any of the context that you do. Your name needs to convey three things.

CPAN is mostly without context other than "This is something in Perl". We can categorize modules, but that categorization lives outside the module and disappears once someone downloads it, blogs about it, or uses it in their code. As a maintenance programmer, what would you think about seeing:

   use XYZ::WWR::JKL;

You might think that's a silly example, but we've seen modules without a single vowel and no recognizable initializations.

The task or the feature the module provides has a context, usually given to it by its author who created it to scratch some itch. In the author's mind, it's always obvious what the module does and what the name means. Other people don't have that context, and the name needs to provide it.

For example, in the Debian Linux distribution, the package manager is called dpkg. As a name alone, however, that has no meaning to someone who doesn't use Debian. In the context of Debian, it makes perfect sense. In the context of Perl, it means nothing so people need extra clues.

Almost any abbreviation or acronym is going to be ambiguous. If the first page of Google hits for your initialization isn't about your topic, then you have the wrong name.

Some modules are designed for a particular task. Other modules perform a general set of tasks. Your name should describe the level of generality. What does an HTML module do? Well, you really can't tell from that name. How about HTML::Parser, HTML::TreeBuilder, and HTML::SimpleLinkExtor? Those names give you more information about what the module can do for you. When you choose your name, when want to show that same kindness to other people.

Many of the modules on CPAN work towards similar goals in different ways, or work in the same way towards different goals. How many Config and Getopt modules can you find on CPAN? Can you tell what they all do just from the name? If your module is going to live under the same namespace as other modules, how is yours different? Why should people use your module over modules with very similar names?

You can distribute applications as Perl distributions. Typically, those sorts of distributions go under the App namespace, like App::Ack, App::Cpan, and App::Prove. The namespace implies that its a ready-to-use program rather than a module.

By convention, the top-level Local namespace should never conflict with anything on CPAN. This allows you to be confident that the name you choose under Local isn't going to conflict with anything from the outside world.

Some projects, such as Moose, DBI, DateTime, and Catalyst, try to organize the activity under their namespace to ensure everything works together nicely. If you want to add a module to such a project, discuss it on their mailing list.

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.

CPAN has been around since 1995, and over time the various administrators have discovered or followed certain conventions to make the designed anarchy a bit less chaotic. As an evolutionary process, it is historically inconsistent but modernly optimal. That is, looking at the past as an example might not be the best thing. Just because other people did it doesn't mean you should.

In general, top level namespaces are bad, unless they are a nexus for several modules under that namespace or they are a fanciful name that describes something more application oriented. You might think that DB is a good name because it's that database portion of your code, but it doesn't say much about what it is doing, and it also happens to be the namespace for the Perl debugger.

That doesn't mean that all top-level namespaces are bad. For frameworks like Moose, Catalyst, or DBI provide a functionality around an idea rather than a particular low-level or general task. They don't live in a hierarchy because they are large enough to stand on their own.

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.

Remember that though you may be the first to contribute to a namespace, you may well not be the last or the only one. Someone might later want to use the namespace, for something unrelated to your modules.

Perl reserves all lowercase namespaces for pragmas. That doesn't mean you can't write a pragma, but you should get the blessing of p5p (perl5-porters@perl.org).

The Net namespace is one of the most abused namespaces out there. Originally designed as a home for the code that knows how to talk various defined network protocols, such as FTP, HTTP, NNTP, and so on, people started using it for code that merely used the network without knowing anything about it. Modules that interact with websites use the network, but they aren't about the network, and they have much better homes in WWW or WebService. If you are implementing a network protocol rather than an application protocol, then Net might be for you. Otherwise, it isn't.

The terms Simple, Easy, Reduced, and Tiny are some of the worst parts of the names on CPAN. They all indicate that the module is a variation of another module, but why is that variation interesting? It's usually missing or hiding some features, less flexible than the original, and in most cases, tailored to the task the author needed. What is that task though? Making it easy for you doesn't mean it's easy for the next programmer.

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 data is "text", please don't.

Unicore/unicore is reserved for the use of the Perl core for Unicode things.

Your module is an API? No kidding? Don't waste space in your name telling people what they already know. If your code wasn't an interface of some sort, it wouldn't be very useful.

Many people, lacking other ideas about what their module does, just use their own name. They might have really good names, but that doesn't help anyone figure out what the code does, even if they do attach Util to the end.

brian d foy <bdfoy@cpan.org>

Jarkko Hietaniemi <jhi@cpan.org>