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!
Perl hacker since 1992.
Thanks Neil!
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.
Remember: name your module for what it *does*, not how it does it.
Ether: ok, so I've got a module MooX::Role::CachedURL. This is a role which gives you a locally cached file copy of a remote file, specified with a URL.
I struggled with the name for this when I created it, considering File::CachedURL, and URL::Cached. What would you go with?
If I do rename it, then I also get to release my dists that use it too! \o/
Great article.
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.
Ahmad: thanks for the kind words.
Lots of Perl-related tools live in the Perl:: namespace, like Perl::Tidy, Perl::Critic, Perl::PrereqScanner. So Perl::IDE:: would be an entirely appropriate namespace, I think.
Hi Neil,
Nice talk as always.
It seems you can read my mind. I have been going through this question for sometimes.
Keep up the good work.
Mohammad S Anwar
Mohammad: thanks. I'll be looking for some released from you next Saturday (16th) then! ;-)
IMHO branded names in the top-level domain should be encouraged especially for end-user products. Such as IDEs, web servers (e.g. Starman) and others.
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 agree wholeheartedly with your opinions here Neil. I think there should even be a CPANTS field for appropriately-named module/dist.
I truly hate "branded", non-descriptive names. It gives me the impression that the author was lazy or a trying to be a hipster, and lowers my expectations on the quality of their contribution.
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.
BTW See the naming section of Starman.
Keep in mind that Role:: is a top level namespace.
Maybe
Role::Attr::CachedURLThough looking at what you have, a few things may be true:
A) The role may not be applicable if you aren't using Moo and thus won't work with "
Role::Tiny::With", mostly because of that requirement you use Moo to set the URL.B) The current interface seems limited in that it can only compose in one attribute, where multiple may be desirable.
B is currently YAGNI territory.
Hm, looking at existing things, it may even be better to write what you currently have if you don't plan on going beyond and allowing B, to call it:
MooX::Role::HasURL::Cached"
HasURL" is much more clear that it associates a 1:1 mapping that is not very flexible.But IMO, if you want to get the "MooX" part out of the name, then you need to have an interface that doesn't require the user to
use Moo; ... has +url =>Say:
use Role::HasURL::Cached { url => 'myurl' };However, if you were to write the logic in terms of
Package::Variantor similar, you could do:use Role::URL::Cached { url_google => 'http://google.com/', url_metacpan => ...., };But I don't see you easily unbriding it from making the user use Moo/Moose.
Even those
importstyle tricks I've used, while nice, are prone to confuse users who expect to do:with Rolenotuse RoleAlso, 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...
Yes, posting a comment from the "Preview" page is broken.
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.