There is a famous quote which says:
"There are only two hard things in Computer Science: cache invalidation and naming things."
Drupal is no different. The secret sauce behind Drupal's powerful hook system is a simple naming convention and it all starts with naming your module. Choosing the right name for your module is important, as is understanding a couple of potential pitfalls you may encounter down the road. Some of which are obvious and some of which can sneak up on you.
At Drupalize.Me we've been working on updating our site to Drupal 7 and in the process have been rewriting, refactoring, and in general just cleaning up a lot of our custom code and features. As you can imagine over the last two years of development on the site, and with a number of different people working on things at different times, our custom modules directory is a bit like walking in to a book store that's going out of business. There is no rhyme or reason, just books.
So this time around we're trying to standardize things a bit more and what follows are some things to be aware of when naming your custom module.
Side note: Remember that exports from the features module are actually just automatically generated modules and are thus subject to the same naming conventions.
Namespace collision
This happens when you have two modules with the same name. In short, don't.
There's nothing in Drupal that prevents me from writing a new custom module named user and placing the new code in the sites/all/modules directory for my site. However, doing so has some major ramifications. When Drupal is determining what modules are available on my site it does so in a very specific order it starts with those in the root modules directory followed by those in the sites/all/modules directory, then any in sites/default/modules, and finally if you're using a multi-site architecture any that are in the site specific folder like sites/drupalize.me/modules. It gets interesting when you have two user.module files though, as Drupal will use which ever one it finds last and ignore any others, regardless of what is in that file.
Don't name your module using a name that is already taken by an existing module. Obviously this applies to all the modules in the core modules directory but I would also extend this to don't name your module using a name that's already taken on drupal.org. You never know when you might want to use the Unicorn module sometime in the future or you might want to contribute your sweet module back to the community.
Unsure if the name is available. No problem just visit http://drupal.org/projecgt/{MY_MODULE_NAME}, if there's a page there, pick another name.
Organization and Findability
When choosing a name for your module choose one so that when someone is scanning a directory full of modules they can get at least some idea of what each one does. This makes it easier to find the code you're looking for. Something I tend to do often is use the name of the site I'm working on as a prefix for any custom module names, e.g. google.com modules would start with googlecom****.module. However, keep in mind the next rule of thumb when going this route.
Will you ever contribute this module or is it completely application specific code that will never see the light of day? It's common when building Drupal sites to create modules that house code that is so specific to this one particular site that you're not ever going to use it anywhere else. Customizing specific forms or augmenting the features of another module ever so slightly to do things your way. If you think there's even a remote possibility that you'll contribute the code back to drupal.org you probably want to choose a non-project-specific name.
And while naming your module Eldorado Superfly might seem like a fun and witty joke, I suggest you stick to boring and useful names.
Some other tidbits
You're going to be typing these module names a lot so brevity can be nice. For Drupalize.Me we started out using drupalizeme****.module, but have since abbreviated it to dme***.module.
We've also standardized on not including an underscore (_) in our module names. For a while we had names like dme_comments, dme_videos, and others. However best practice is to name your module without any underscores to reduce the chance of namespace collision. Imagine I had a module named views_user.module with a function in it named views_user_load, a common pattern when using wildcard loaders in menu items, for example. Initially this seems safe enough, there's no module with that name already and PHP doesn't complain about two functions with the same name. But take a closer look, and realize that you've just implement hook_user_load on behalf of the views module. Oops.
Finally, we decided to standardize on naming our features module-generated modules differently than our custom code modules. So now all of our features are prefixed with drupalize***, the primary reason here being that it's nice to be able to scan and find things, knowing what's what just from the name.
Recap
There is no end all, be all convention for naming things in Drupal but here are some good guidelines to follow.
- Don't use names that are already in use on drupal.org for custom code.
- Use meaningful names for findability.
- Use domain specific names for code that you're sure isn't going to be contributed back.
- Standardize your team on a naming convention.
And I'll leave you with this joke that my co-worker Jeff is quite fond of:
"There are only two hard things in Computer Science: cache invalidation, naming things, and off by one errors."
Add new comment