NeilB

On Saturday I wrote about naming your distribution, and how that should be based on your (lead) module name. ETHER pointed out that if your module is sub-optimally named, then you should also consider renaming your module (and thus probably the distribution) on CPAN Day.

I thought it would be helpful to expand on that, and give some pointers to resources that might help you with naming.

There's a saying that you may have heard:

There are only two hard things in Computer Science:
cache invalidation and naming things.

— Phil Karlton

Naming modules is hard, particularly when someone else has already taken the 'obvious' name for your module. perlmodstyle has a section on naming your module, as does perlmodlib. Their suggestions are factored into the following things to consider:

• If there are other modules on CPAN that do similar things (you know, the ones you list in your SEE ALSO section :-), then what namespaces are they in? Is there a better namespace than the one you're currently using?
• Where possible, be descriptive. If you module handles fractions in the English language, Lingua::EN::Fractions isn't a bad name, Chipmonk is. Sure, there are projects like Moose, but most modules aren't going to have that kind of mind share, so make the module easy to find.
• Don't start a new toplevel namespace. For example, if you're creating an interface to trello, don't just call it Trello. Yes, someone searching for 'trello' would find a module with a top-level name, but it doesn't help with the grouping together of similar modules, and discovery of them by potential users.
• The namespace Net is abused. For example you might think Net::Trello is a good name, because it's an interface to the trello service, accessed over the 'net. But Net:: is for things like implementation of network protocols, like Net::FTP. Perl interfaces to web services should go in somewhere like WebService::.
• Don't be afraid to go for deeply nested namespaces. People won't be typing your namespace very often, so prioritise on useful / accurate naming over brevity. If your module is a class that people are going to type multiple times, there's always the aliased module, and others like it.
• If you think you've found a good namespace, look at the other modules in it, even if they're not similar to yours. Do they seem like good bedfellows?
• If you're not sure, post about your module to PrePAN. This is a good way to get feedback from other members of the community.
• You could ask on IRC, or even write a blog post about it, asking for suggestions.
• thesaurus.com might help you find a name, if the obvious / best one is already taken.

Renaming your module

Having picked a new name, how should you go about renaming your module and distribution? Here's a process you could follow:

• Create a new distribution by copying your existing one and renaming both the module(s) and the distribution.
• In the new module's documentation, make clear that this module is the replacement for the old module name, and that eventually the old-named module will go away.
• Release the new distribution to CPAN.
• Update the documentation for the old module. Change the abstract to include "[deprecated]" or similar. In the first paragraph of the DESCRIPTION section, say that the module has been superseded, and link to your new module with the L<> formatting code. You release the new distribution first so that this link will work.
• Release the old distribution to CPAN.
• If there are other distributions on CPAN that use your old distribution, submit a ticket to let them know about your new module. If they're on github, submit a pull request to switch to your new module. If anyone's submitted bugs, email them.
• Once all other CPAN distributions have switched, pick a date in the future (eg a year hence), and put in the old module's documentation that you'll remove it from CPAN on that day.
• Wait
• Remove the dist from CPAN, and free up your ownership of the namespace via PAUSE.

If your distribution has been on CPAN for any length of time, then you should still do the above, even if there are no other distributions using yours — you've got no way of knowing who is using your module in something that isn't on CPAN.

If you do this on CPAN Day, then it counts twice: you get to release both the old distribution and the new one!