WordPress Theme Development Best Practices

Creating a high quality WordPress Theme is about more than just a nice design. What’s going on under the hood is equally important: using the right Template files, writing clean code and testing for all kinds of content.

Luckily there is a wealth of information, plugins and other helpful tools available on the web. This is an overview of the best resources to help you develop Themes according to the best practices.

Getting started

For those new to Theme Development, the Theme Development article in the WordPress Codex is a good starting point. It gives an overview of all of the different aspects of a Theme.

If you want a more hands on approach, work through the ThemeShaper WordPress Theme Tutorial: 2nd edition. It is divided into 16 lessons, with code samples and detailed explanations that will help you build a Theme from scratch.

There are other approaches to building WordPress Themes, a very comprehensive overview of the options for WordPress Theme development is available on Smashing Magazine.

Another good resource for developers that are new to WordPress is Inside WordPress Actions And Filters that provides an introduction to the Plugin API.

Coding Standards

WordPress has well established coding standards for PHP, HTML and CSS. Following these standards will make it much easier for other developers to read and modify your code.

You can find the WordPress Coding Standards for PHP and HTML and Javascript in the Codex. The CSS Coding Standards are available in the Core Contributor HandBook.

Localization and Internationalization

Making your Theme translation ready is strongly recommended. In developer speak this means l10n and i18n, and the Codex has an introduction about the code side of internationalization.

In addition to this, Otto has written two very in-depth articles about the pitfalls of i18n as well as an overview of the lesser known translation functions.

If you are multilingual and want to translate a Theme, you can look at the Files and Tools page in the Core Contributor Handbook.

Theme Options and the Customizer

Thanks to the Settings API, you can create a custom settings page in the WordPress Admin to help users customize your Theme.

Proper handling of Theme options is very important, so if you build a custom options page, please follow the instructions in this tutorial.

With WordPress 3.4 came a very cool feature, the Theme Customizer. It allows users to change the appearance of a Theme via different controls, while being able to preview the changes live.

Leveraging the Customizer in your own Themes is pretty straightforward, and Otto has written three comprehensive tutorials to get your started:

Testing your Theme

Helpful Plugins

  • Log Deprecated Notices helps you to find calls to no longer supported WordPress API functions.
  • Theme Check is an automated check of your Theme against a set of Theme Review Guidelines.
  • Theme Mentor is based on the Theme Check, but it performs a larger number of tests.
  • RTL Tester helps with debugging Themes with support for right-to-left reading languages.
  • Monster Widget helps with testing WordPress core widgets without having to add them one by one to each widgetized area.

Test Data

A Theme should be able to deal with a variety of user generated content. To help you to test your Theme, you can use WordPress’ Theme Unit Test.

The test consists of a XML file that you can import into your development environment as well as a set of instructions on how the Theme should handle the test data.

If you want a more exhaustive set of test data, you can download WP Test by Michael Novotny. WP Test is an Open Source project and the data can be found on Github as well, so if you encounter a bug that isn’t covered, don’t be shy and contribute.


The WordPress Theme Review Guidelines are the de facto standard when it comes to best practices. In fact every Theme hosted in the WordPress.org Theme Directory needs to respect these guidelines.

In addition, there is The WordPress.com Public Theme Guide, that outlines essential guidelines for high quality Themes on WordPress.com.

Showcase Themes

There are a couple of well developed Themes that can serve as a showcase for development best practices.

A good starting point are the default WordPress Themes: TwentyTen, TwentyEleven and TwentyTwelve. As a new core Theme gets added every year, this is a good way to keep up with the latest features.

The _s Starter Theme is another good inspiration and can serve as a foundation for building your own custom Theme.

And finally there is Oenology, a Theme that has been specifically build to serve as an educational reference for developers.

Interesting Presentations

Themes are an often discussed subject at WordCamps. Here are a few interesting presentations that you can watch:

Did I forget something?

Let me know in comments or write a post on your own blog.

2 thoughts on “WordPress Theme Development Best Practices

Comments are closed.