Don't be afraid to rename your module / dist

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!

Tagged as:

14 Comments

For authors of modules in the MooseX:: or MooX:: namespace: please note that this namespace ought to be used only for Moose *extensions*. If your module is simply a role that happens to use Moose to provide attributes to the consuming class, it's not an extension. Consider renaming to something::With::AnotherThing instead.

I was wondering what is a good namespace suggestion for Perl IDEs, editors in general. We have Padre, , Kephra, Farabi and EPIC. None of which are conforming to any CPAN namespace standard. Three of which are currently CPAN installable.

True, but how do you know Starman is a web server from the name alone. If I was searching using metacpan for a web server, I will not find it for sure. So you need to market your branded module more just to reach to the same level of visibility of a properly name-spaced module (e.g. WebServer::Starman).

Maybe distribution tags is a solution to the search problem. Metacpan can allow people to tag modules and META.yml can include initial tags. What do you think?

I think what you wrote (tagging) is a much better way, especially as some people might look for webserver, but others will use different words. IMHO the tagging should be both by the author via the META files and by the users of MetaCPAN.

Also, Please remind me not to waste time with the edit process of commenting on blogs.perl.org to write a decent comment.

blogs.perl.org, after allowing me to review my comment with preview multiple times, spontaneously decided to tell me my session had expired and summarily discarded all my effort when I finally went to submit it.

It is only by the grace of perseverance and TextAreaCache that I was able to retrieve my comment from browser memory, go back to the blog page, and submit it fresh with no preview process.

I find it hard to communicate just how horrific I find blogs.perl.org, both as a person commenting, and a person using it as a blogging platform.

@Ahmad
Just remember that namespaces are quite an old-school way to provide search hints.

Searching the Internet has long ago moved away from guessing domain names, and we now rely on search engines that analyze content and, in particular, use links to bubble interesting content.

SEO science now relies on links between content. That's why linking related modules from POD is more important than ever, so fill your own SEE ALSO section and send patches to others SEE ALSO for them to link to your code.
Write blog posts about it, tweet it...

The workaround is to preview, then hit back, (if necessary, edit it some more, preview again, and go back again... until you are satisfied with your comment), and then post the comment. You need to post it from the first comment form you started using, not from the preview pages.