Dear WP plugin developer, please…

Follow Coding Standards #

WordPress has its own coding standards, which I highly recommend. But if you don’t like them, use some different ones. I really probably won’t care. But, please, please, please, stick to some kind of standard that is readable. If you don’t follow any standard, your code is inconsistent at best or hardly readable at worst.

I’m not asking you to do this for the sake of myself and other developers, who might want to fork your plugin (if it is open source). I’m asking you to do this for your own sake. If you can’t read your code, it is more likely to be broken, and more difficult to fix. If you want to maintain your plugin, you should write maintainable code. For your own sanity.

Only enqueue scripts where needed #

Just once in your life, try maintaining a site that uses about 50 or 100 plugins that are enqueueing scripts. Guess what. Your site will be handling requests for all sorts of scripts and styles, sending KB or even (yes, really) MB of data that it doesn’t even need to. Oh, and did I mention that it could also make your site kind of slow (unless you are using a good CDN, then it might load reasonably fast)? The moral of the story? Register your scripts on 'init' or 'wp_enqueue_scripts', by all means. But never, ever, ever enqueue a script or style unless and until you absolutely have to.

Prefix function names #

Not doing this is one way to cause conflicts, and even kill sites!

Real world examples of bad function names:

  • user_list()
  • register_settings()
  • transition_db()

So, every function (and class, and global variable, and option, and post meta field, etc.) should have a prefix unique to your plugin. Many plugins use a kind of acronym, like bp_ for “BuddyPress”. This makes the function names shorter and easier to write, and that’s is all right to a point. But consider that a prefix like that may not really be as unique as you think. Taking the letters A to Z and the numbers 0 to 9, there are:

  • 36 1-character prefixes
  • 1,296 2-character prefixes (but WordPress already uses wp_, so make that 1295)
  • 46,656 3-character prefixes

That’s a total of 47,987 unique prefixes in three or less characters. Now consider that there are currently over 31,000 plugins on WordPress.org alone. Within a few years that 50,000 mark will probably be a reality. I think it is a safe bet that the two-character acronym for your plugin is probably already being used by another plugin. And the 3-character prefixes will soon run out as well. So you may want to carefully consider using your plugin’s entire name as a prefix (if it is reasonably short), or a longer prefix, say 4 or 5 characters at least. For example, in my WordPoints plugin, every function is prefixed with wordpoints_. (I couldn’t have used wp_ anyway since WordPress already uses it.)

Another idea is to use a shorter prefix on some functions, and only the longer prefix on others. Although this introduces inconsistency, it might still be a good choice in some circumstances. For example, if you had a plugin called Post Colors, you could use a prefix like pc_ on functions that were unique to the purpose of the plugin, like pc_add_color_to_post(). It’s unlikely that there will be another plugin with the pc_ prefix that has a function with that name. But then consider a function to update your plugin’s settings. You could call it pc_update(), but that is much more likely to be used in another plugin. In that case you could call the function post_colors_update() instead.

Personally, I’d prefer to choose a long, unique prefix and use it consistently throughout the plugin.

Use sprintf() with L10n instead of splitting sentences

It’s in the plugin developer handbook now, so I’ll just quote from there:

Use format strings instead of string concatenation – translate phrases and not words –

printf(
__( 'Your city is %1$s, and your zip code is %2$s.', 'my-theme' ),
$city,
$zipcode
);

is always better than

__( 'Your city is ', 'my-theme' ) . $city . __( ', and your zip code is ', 'my-theme' ) . $zipcode;

Don’t use error silencing #

I’ve been surprised how many plugins I find that heavily use error silencing. While there are rare cases in which it really is useful to use the @ symbol to silence errors, when used often it can easily introduce unexpected side effects. Once I spent hours (probably more than 6) chasing a bug. I knew that a fatal error was occurring, because only half of the post would get output, and then after than nothing. The funny thing was, no matter what I did, I couldn’t get PHP to give me an error. Not a single peep. I finally discovered that the cause was a shortcode. The shortcode function was complex, and called a bunch of other functions that called a bunch of other functions, etc. I was finally able trace the point where the script was dying to a bit of code that was calling a function, with (you guessed it), an @ in front of it (to silence any pesky notices). (Removing the @ revealed the problem was that the devs hadn’t heeded my advice about checking for PHP libraries before using them.) I haven’t been able to use the @ symbol lightly since. Hey, it only takes an instant to type, but it can take hours to un-type. You already know the moral of the story: don’t use @ to silence errors. Ever.

(This disclaimer is included for those of you who are thinking to yourself, “Hey, there are times that it can actually be useful.” Yeah… if I remember correctly, I think I came upon one of those situations once…)

But actually that isn’t all. Some plugins do error_reporting( 0 ). It’s true. They really do. And guess what! They don’t even set the error reporting back to the previous level afterward. There are two reasons that plugins shouldn’t be doing this. You already know what one of them is. The other is that this is an INI setting. Generally speaking, plugins shouldn’t be changing the INI settings unless they have a good reason. A very good reason. The site administrator has the INI settings the way they are for a reason (OK, I know, many users haven’t a clue what the PHP INI settings are, so their host has the INI settings the way they are for a reason). Changing them is a bad idea and makes debugging harder.

Check that a PHP library is available before using it #

I’ve met with these fiends on several occasions (one instance is recounted above). It is easy to assume that it is safe to use EXIF functions, for example. But the truth is that not every instance of PHP is compiled with EXIF. Sometimes the library isn’t being used. You have to think of this before you start using it, or else you will break websites. Guaranteed. Like I said, I’ve encountered this more than once. Suddenly, something mysteriously doesn’t work.

The solution is to make sure you check that the function exists before you use it. Sometimes it may not be necessary to use the function at all. In other cases it may be integral to your plugin, and in that situation you should be showing the user a notice when the function(s) aren’t available.

Conclusion #

OK, so I apologize for the rant. If you’re a new plugin dev, and you just realized that you’ve made some of these mistakes, don’t worry. You’re not alone. I have made some of them myself, because we all start somewhere. That is really part of the beauty of WordPress. Almost anyone can start out just wanting to build a website, and end up as a plugin developer. And we all end up looking back at those first plugins we wrote, and thinking, “Did I really do that?”. Yep. We did.

So, I didn’t write this post just to bash newbie plugin developers and all of their poor practices. (Only part of me did. :) Rather, I wrote it to possibly help a few plugin developers improve their skills. And I’ll probably be adding new sections to it in the future (each time I need to rant).

Leave a Reply

Your email address will not be published. Required fields are marked *