How to Avoid Common WordPress Theme Development Mistakes

WordPress is known for being incredibly flexible, especially when it comes to theme and plugin development. If you ever want to see proof, just ask a group of developers how they’d implement a specific feature. The chances are that you’ll receive several different methods for accomplishing the same result. Support forums are littered with these kinds of examples.

But with that flexibility also is the reality that it’s easy to do things the “wrong” way. Now, in this case, “wrong” means that something is either inefficient or a bit of a pain to maintain down the road. While it may work in the sense of being functional, there are usually better ways to get things done.

Let’s have a look at five of the more common mistakes found in theme development, along with alternatives that will save you future headaches.

1. Using Absolute URLs in Templates

If you’ve ever looked at the HTML code a WordPress page or post produces, you’ll notice that both images and internal links use absolute (full) URLs. But this isn’t the best way to get things done when adding code to your theme templates.

As an example, let’s say you are developing a website that is using a temporary URL. A hardcoded absolute URL in a template means that you’ll have to manually make code changes when you are ready to launch the site on its permanent domain. While this can be done, it’s too easy to forget all of the spots where this type of code could be lurking.

WordPress has built-in ways to determine the correct URL – pulled right from the Settings > General area of the Dashboard.

For a link, echoing esc_url( home_url() ) will provide a full path to the home page. So, instead of explicitly placing the URL in your code, you could add a simple link back to your home page like so:

<a href="<?php echo esc_url( home_url() ); ?>" />Home</a>

What’s more, you can also use this to point to secondary pages. For example, if we wanted to link to our site’s About Us page, we could use the following code:

<a href="<?php echo esc_url( home_url() ); ?>/about-us/" />About Us</a>

A similar snippet also works for images. This example pulls an image from our active theme’s /images/ subfolder:

<img src="<?php echo esc_url( get_stylesheet_directory_uri() ) ; ?>/images/hello.png" />

2. Adding Scripts and Styles Directly to a Template

Using third-party scripts and styles with WordPress is a world of its own. When you first start out in building themes, you may be tempted to simply place <script> or <style> tags, or even a Google Font embed code directly into your theme’s header. This is generally how things are done with static HTML sites, so it makes sense to do the same here.

But, like just about everything else in WordPress, there is a better way to go about it. Instead, take advantage of wp_enqueue_script() and wp_enqueue_style() – which add scripts and stylesheets to the correct spots for you. It also makes managing assets that much easier, as everything is called from your theme’s functions.php file.

Rather than reinvent the wheel here, the WordPress Theme Handbook has a fantastic guide on how properly add scripts and styles to your theme.

3. Calling Outside Instances of jQuery

In a related note, one of the hidden secrets of WordPress is that it already includes a copy of jQuery, along with several popular UI features. So, you don’t need to install jQuery or call it remotely. This makes it easy to take advantage of the popular JavaScript library and implement elements such as tabs, datepickers, dialogs and a whole lot more.

The only catch is that you have to specifically enable the items you want to use through your theme’s functions.php file. While that creates a bit of a learning curve, it also cuts down on bloat.

And, truth be told, it’s not overly difficult to implement a desired jQuery UI element. For example, to enable the use of jQuery UI Tabs, just add the following snippet to your functions.php:

function my_jquery_elements() {
   wp_enqueue_script( 'jquery-ui-tabs', array('jquery'));
add_action( 'template_redirect', my_jquery_elements ', 10 );

This tells WordPress to load in the element from its already-existing library. From there, design your tabs and define them as specified in the jQuery UI documentation.

4. Taking Customization Too Far

The ability to add custom fields and custom post types can make life for both developers and site content editors much easier. They offer convenience, better content organization and a more intuitive UX. But sometimes we take it too far.

I’m a huge fan of custom fields, for example. But even I admit that there have been times when I’ve customized a theme to the point of inflexibility. Fields are great for setups where we know exactly what content will need to be input – like the fields of a staff member profile.

However, it can get messy when there are inconsistencies in the types of content someone wants to add. Clients are notorious for having “minor” exceptions in content that can make using customizations more difficult. Conditional logic can account for some of this, but you can only take it so far before the UI gets out of hand.

There are no hard and fast rules for this type of customization. The only thing we can really do is use our best judgment about what should be customized and what can be better left to either the WordPress content editor or even a niche plugin. When we do add fields or post types, just know that things could change down the road and try to build with that in mind.

5. Failing to Comment Code

I’m going to make another admission here: Commenting code is not one of my strong points. It’s not that I don’t use comments at all, but it’s more that they aren’t very articulate. Usually, I’ll point out the start and end of particular items with not a ton of insight in-between. Should I be doing more? Probably so.

Commenting is important because it at least provides some reference points within the code. When digging through PHP or JS files that contain more than one thing, you’ll want to know where to find a particular item.

Even if you’re the only one who will ever edit that code, comments are highly recommended. If, for instance, you need to change something six months from now, it’s unlikely that you’re going to remember the exact spot you placed a snippet of code.

So, I’m not going to be a huge hypocrite and implore you to comment everything with great depth. But I will say that even a minimal effort here makes future maintenance easier for you or another developer that has to comb through your work.

Better Techniques Over Time

Building your own WordPress theme can be a great experience. But it does take a good bit of practice to pick up on the finer details of creating a well-coded theme and easy to maintain. The more experience you gain, the more your techniques will evolve.

I can honestly say that the first few themes I put together were nowhere near as efficient as they are now. And I’m also certain that they still might not be up-to-snuff when viewed by a truly expert developer. In that sense, our evolution is a constant one.

Finally, I’d like to note that I have personally made every one of the mistakes mentioned above. It’s only through trial and error, along with several visits to the Codex, that I found out how to start doing things the “WordPress Way.”

The lesson is that we’re all going to make mistakes. But each one provides us with a chance to learn and improve.