5 Common Theme Development Mistakes and How to Avoid Them

Review is a key part of Theme Wrangling, so we spend a lot of time looking “under the hood” at themes. Here are some of most common theme development errors that come up in the review process, and some tips on how to avoid them.

1. GPL-incompatible Licensing

Just because it’s “free” doesn’t mean it’s open source. If you’re building your theme on a framework or starter theme, or if you’re building a child theme, the foundation/parent theme must be GPL or GPL compatible.

In addition to the theme’s license, always check the licenses for bundled resources – images, scripts, fonts, or icons sets – to ensure they’re GPL compatible, and state their respective licenses in the theme’s README. When in doubt, contact the original author to inquire about the license (and perhaps encourage them to switch to a GPL-compatible one if they haven’t already).

The WordPress Codex has helpful information regarding GPL and theming:

2. Poor Code Quality

Reviewing code can be time consuming, especially when it’s not your code. Inconsistent styles and lack of spacing makes your theme’s code harder to debug and maintain… and it’s just plain messy. Adhering to the WordPress Coding Standards for PHP, CSS, and Javascript makes it easier for yourself and others to read, understand, and maintain your theme going forward.

3. Fails the Theme Unit Test

The Theme Unit Test is a set of data used to test for visual bugs and inconsistencies. We know you’re excited to share your theme with the world, but before you do, test it thoroughly with the dummy content provided. You’ll catch a lot of the common issues that come up in theme review, which in turn speeds up the review process.

4. Copy Pasta Code

Does this scenario sound familiar? Your favorite blog uses a unique Javascript slider, and you want to use it in your theme. You look at the source, then copy and paste the blog’s script into your theme and it appears to work – success!

Well, maybe, or maybe not. It’s important for you to understand the code that goes into your theme for a number of reasons – security, usability, compatibility, and licensing concerns among them. In short, if you didn’t write the code, you should still familiarize yourself with its source and license, and have an understanding of what the code is doing and how it works.

Don’t get me wrong – sharing and working with open source code is encouraged! It’s a great way to learn. But simply finding a script and copying it into your theme does not help you grow as a developer, and there is a good chance it won’t help your theme in the long run, either.

5. Improper Data Validation/Sanitation

Last but definitely not least, it’s important to make your theme as secure as possible. If you allow users to change settings, there are that many more entry points for harmful data. A common misstep in theme development includes failing to validate data going to the database and sanitize data coming from the database, leaving your theme (and your users) open to malicious code. There are a number of ways to prevent this, and you can read about them in the Codex:

It is also recommended that themes use the Settings API to include theme options, but I prefer to use the Customizer, and keep theme options to a minimum. Either method is valid as long as you follow appropriate validation/sanitation procedure. Read more about the Settings or Customization APIs:

As always, if you’re looking for a secure, stable, properly coded, and GPL-compatible base theme, you can’t go wrong with our very own _s starter theme. _s addresses several of the above concerns out-of-the-box, which speeds the development process and decreases your chances of making one of the above mistakes.

I hope this guide will help make your future themes that much more awesome!

Author: Caroline Moore

I'm a front-end engineer, web developer, illustrator, photographer, painter, wife, and proud mama to two amazing kids. I have too many hobbies, and I make stuff for WordPress.com.

7 thoughts on “5 Common Theme Development Mistakes and How to Avoid Them”

  1. Point 2 in your article is something that I see so much of in so-called ‘premium themes’; poor CSS and HTML structural markup, overuse of CSS.

  2. Caroline… thanks for the short sweet tips guide, unfortunately all too many theme developers don’t take the time to be a thorough as you suggest:(

  3. Totally agree with #2. I have installed some themes with pretty good design, but the code is really poor. I mean the designer messed everything up in the code making it complicated to fix everything and decrease your loading time.

  4. I totally agree with two and four. It is especially helpful when you have so many lines of code to look through and so many pages to learn how another developer created a certain look or action.

  5. For #2, I like to add that effort should be made to make the code simpler. This is because users will most likely edit your theme to suit their needs, even if the theme is customizable using admin page. I have bought a theme where the nesting of tags is too much and hard to follow.

Comments are closed.