Nine Common WordPress Code Issues to Avoid

Nine Common WordPress Code Issues to Avoid

There are many articles out there about fixing WordPress code errors and many more on mistakes to avoid as WordPress users.

In today’s article, I thought it would be helpful to take a look at some coding issues which work, but would be considered inefficient, bad code or bad practice.

I’ll focus on some of the most common problems I’ve seen around and some errors which I’m ashamed to say I’ve committed in the past myself.

A cleaner sign
Let’s take our mistakes to the cleaners!

1. Not Enqueueing Google Fonts

Google fonts are added to a theme or plugin either by hardcoding them, or by allowing users to choose them. If you allow users to choose the fonts, the code behind it can get a bit complex and you may forget that adding a link in the header is not the way forward. Enqueueing them is just as easy as any other stylesheet:

Note that the fonts should only be included on pages they are actually used on. See the next section for more information.

2. Enqueueing Resources Where They Are Not Needed

Another common practice is to use the enqueues like the example above, but without regard to when they are actually needed.

On the front-end you will probably want to use your fonts on all pages, but on the admin side you may only be using them on your plugin’s setting page.

Let’s take a look at some ways to target enqueued assets better:

Front-End Targeting

On the user-facing side of your website, template tags are your friend. The Twenty Fourteen default WordPress theme gives us a great example when enqueueing the comment reply script, which gives us the inline comment form:

This script is loaded only when three conditions are met at once: We must be on a single post, comments must be open, and the thread_comments must not be empty. This makes sure that the script is only used when it is truly needed.

Another example I like to mention as often as possible is how you can enqueue scripts and styles for shortcodes. If you have assets which are only needed when the shortcode is actually displayed you can register the assets as usual, but only enqueue them in the shortcode. Here’s a quick example:

Admin Targeting

Admin assets can be targeted in two ways. Functions hooked into admin_enqueue_script receive the file name of the current screen you are viewing.

Hook is an extremely confusing name for this parameter, but I have left it in since the WordPress Codex uses this convention.

This is a good way to go about things if you want to target a specific page, but what if you want to target the edit page for a single page (and not a post)? Both instances would be edit.php with our example above. In these cases you can use the get_current_screen() function.

This gives you a lot more info about where you are so you can target pages more effectively. To target only edit pages for the page post type, you could use the following:

3. Using The init Hooks For Everything

init and admin_init is the first hook available after WordPress has loaded but headers haven’t been sent. As such, they are the go-to solution for all our pre-header needs. From legitimate uses of adding post types and text domains, to unnecessary upgrade routines and functionality specific things like enqueuing and adding menus, developers use them for everything.

One great way to determine what hook you should use is to look at the codex. If the codex creates admin menus by hooking into admin_init (it doesn’t), then go for it. Since it’s apparent that admin menus use a dedicated admin_menu, that is what should be used.

Often your features will work no matter which pre-header hook you choose. This doesn’t mean you are writing good code. If a developer wants to modify your code or you come back a year later you will have no idea why your remove_action() call isn’t working.

4. Too Many Options

If you are creating a plugin and you end up adding a great number of entries into the options table, you are doing something wrong. The solution here is to save all your options as an array. Remember, you don’t have to worry about saving your data as a string, WordPress takes care of all that behind the scenes.

The only time you should use multiple options is if you have sets of options which really aren’t needed all the time. If you only need some options on an admin options panel, you could create a separate options field for that and specifying that it should not be auto-loaded.

5. Reinventing The Wheel

If something seems like there should be a function for it, more often than not, there is. I’ve seen people shy away from using WP_Query because it pulls so much data – they just need IDs. So they end up writing something like this:

This has the drawback of being completely un-modifiable by hooks as well as doing something WordPress can do on its own:

This can be applied to many, many use cases. From pagination to uploading files and obfuscating email address, WordPress has functions for tons of things.

Part of the reason people try to reinvent the wheel is not knowing a function is there. This is fine, after a few Google searches these problems are solved. The other reason is optimization. The urge to “return only IDs instead of post data” drives people to try and write more efficient code.

What people forget is that in 99 percent of cases convention should win over configuration. WordPress is by no means perfect, but it is well-optimized. The speed gain from most of these ventures is negligible compared to the loss of code clarity and standardization.

6. Database Clutter

This has to do with making sure that your plugin cleans up after itself. If your plugin is deleted it should leave no trace of its existence in the file system or in the database. Make sure to remove all options and other data  you’ve created.

There are two ways to go: The uninstall hook or the inclusion of uninstall.php. Since uninstall.php is recommended, I will not go into detail about the hook itself. To read more about this, take a look at Plugin Developers – Use Uninstall.php Please at WP Tavern.

7. Not Using Child Themes

This is one of my pet peeves as it has caused me a lot of headaches with users before. Even if you are changing a single line of CSS or you are just increasing the excerpt size of a downloaded theme, use a child theme.

Child themes provide the only way of being able to update a theme after you’ve modified it (without loosing your changes). Child themes will always use the files of their parent theme, unless that file is specified inside the child theme.

One notable exception is the functions.php file, which is loaded before the parent’s functions file to ensure it can overwrite it.

Child themes are so easy to create. If you want to modify Twenty Fourteen, just create a directory in your themes folder, name it anything you want and add a stylesheet with the following content:

Create a functions.php and use enqueuing to pull the stylesheet of the parent:

8. Not Supporting Child Themes

On the flip side of the coin are themes which have poor child theme support. There are roughly two things you need to do here: Make sure to use get_stylesheet_directory_url() instead of get_template_directory_url() where appropriate, and wrap overwritable functions in “if” statements.

The above 2-in-1 example shows how you can make sure child themes can re-define your functions and how the usage of get_stylesheet_directory_url() is helpful. Otherwise WordPress would always look for the image in the parent directory.

9. Incorrect/Missing Language Support

In this day and age of our interconnected society, there’s just not reason not to make your work multilingual. It’s so easy to do, all you need is to use the language functions and make sure WordPress uses the language files if they exist.

To make a string translatable simply wrap it in the __() function or the _e() function if you’re echoing it, and make sure to add your text domain:

For more information on how translation works and how you can generate the language files, take a look at the l18n for WordPress Developers article in the Codex.

The List Goes On?

There are a lot of little tidbits WordPress users – including myself – do wrong. If you have any pet peeves of your own, or you know of something major I’ve left out please do let us know in the comments.

Image Credit: Pete Zarria from Flickr.