5 Cardinal Sins of WordPress Theme Development

We talk alot on this site about tips and tricks for getting what you want out of WordPress… but today we’re going to take a step back from the technical stuff to look at some practices, bad habits, and coding faux pas that would be better left in our past. So, forgive the heavy-handed post title (haha!), we’re about talk bring up 5 surprisingly common practices that are blemishes on the platform.

Two of the nicest things about working on WordPress Themes is that fact that we get to target in an incredibly flexible environment (that is, the web) and we have solid documentation to help guide us through the process (that is, the WordPress Codex).

After all, if the theme works, does clean, maintainable code matter?

But there’s a danger that exists in theme development, too: we can completely forgo best practices for working with the web and completely ignore the documentation. Specifically, there’s nothing that forces us to write clean, maintainable code. After all, if the theme works, does clean, maintainable code matter? Furthermore, why go through the effort of following WordPress best practices if the theme appears to work fine?

Weak arguments, right? I don’t know – the more I’ve worked in the WordPress space, the more I’ve been surprised which how much bad code actually exists. As such, I thought it would be fun to outline five cardinal sins of WordPress Theme Development.

Ignoring The WordPress Codex

As with most programming languages, frameworks, or libraries, WordPress includes a massive amount of documentation. The WordPress Codex is arguably the best resource that developers have for working with WordPress. After all, it provides documentation for the majority of the application.

But the WordPress Codex often goes above and beyond standard documentation – in addition to supplying function names and parameters, the Codex provides rich examples for how to use many of the API functions. After reading any given article, you’d be hard pressed not to find a clear example of how to the function in question.

In addition to the API, the Codex also features a variety of other articles related to development:

• Action and Filter references
• Plugin Development
• Full Function Reference
• Deprecated Function Listing

Whenever I’m working on a theme or a plugin and I hit a point where I think I need to write a custom function to achieve something, I’ll search the Codex first. The majority of the time, a function is already available that helps with what I need.

Every serious WordPress Developer should regularly use the Codex when working on any WordPress-related development project. Ignoring it can often lead to creative, but untested and unstable solutions that can cause more harm down the line than good.

Not Localizing Your Theme

A few years ago, if you were to ask me my thoughts on localizing a WordPress Theme, I would’ve said that it would depend on the marketing that you’re targeting. That is, if you think the audience is going to use a language other than your own, definitely do it; otherwise, there’s nothing wrong with leaving the theme translated in your own language.

Fast forward a few years and WordPress’ is powering millions of sites on the Internet. Sites all over the world are using the application to drive their site’s content. On top of that, it’s becoming increasingly common for developers to supplement their income or even make a living off of working with WordPress.

Because WordPress has been so widely adopted and because the Internet has made the world so flat, the market for any given theme is not limited to a single language. On top of that, WordPress makes it so incredibly easy to localize your theme and it requires so little extra effort, that I now argue that localizing your theme is no longer optional.

For the most part, you need to understand three things:

• The __() function
• The _e() function
• POEdit

Other than that, there’s very little extra overhead that comes with localizing a theme; however, I do recommend that you take a look at the Translating WordPress article in the Codex. It outlines the three things above and goes more in-depth on each.

Theme File Disorganization

Developers talk a lot about code organization and maintainability. Personally, I think that it’s much easier to give lip service to those principles than actually follow through with them, but they are important.

The thing is, they look different for each project type. Some applications are written in a single language and run on a desktop, some applications use two languages and run on a mobile device, other projects – such as WordPress Themes – can use anywhere from three (HTML, CSS, and PHP) to four (through JavaScript) languages. Additionally, certain components of the theme run on the client side, some run on the server side, some community directly with WordPress, and others communicate directly with the database.

To say that there’s potential to sacrifice maintainability is an understatement.

But it doesn’t have to be problematic as there are certain standards that WordPress suggests for organizing your theme files. Specifically, the Codex details how to organize your PHP template files, your stylesheets, JavaScript sources, and images.

• Template File Checklist provides a listing of the files that compose a basic a theme and details what each should include.
• Template Hierarchy provides an explanation for how all of the theme files fit together and how WordPress renders each during its page lifecycle.
• Stepping Into Templates also provides a detailed breakdown of templates and the WordPress page structure for each.
• Theme Development is a massive article that encompasses everything surrounding theme development.

Sure, it takes a little extra effort organize your files rather than just doing enough to “get it working,” but the dividends payout over time as you begin working on the next version of your theme or as multiple developers begin to work on the same codebase.

Disregarding Coding Standards

Of course, file organization is only part of the development process that affects organization and maintainability. Next, we have to focus on how we actually write the code that resides in our files.

After all, not only should we want to provide well-organized files, but easy-to-follow, standard-compliant code as well. Again, the WordPress Codex provides standard set for the major languages that contribute to a theme’s codebase:

• CSS
• PHP
• HTML

A lot to process, huh? The thing is, spending time familiarizing yourself with all of the above pays dividends over time. Applying these standards at the beginning of development is exponentially cheaper than having to refactor an existing theme or plugin.

Additionally, it results in contributing better code back to the community.

Not Testing Your Work

After a theme has been developed and is ready for release, you should do – at the very least – a single of testing. That is, you should verify that the various styles of post data are formatted correctly, that your theme isn’t using any deprecated functions, or that it’s using any functions incorrectly.

Luckily, the Codex provides a number of suggestions and tools to help make this process much easier.

• Debug mode helps to iron out any PHP warnings and/or errors
• The Theme Unit Test is a data file including pre-formatted post data for you to run against your local development environment
• Theme Check is a plugin that will examine that codebase of your theme and provide notes on what needs to be addressed as well as recommendations for improving the codebase.

Of course, there’s also additional testing you can do such as cross-browser testing, HTML/CSS standards compliance, and so on. The Codex outlines even more testing suggestions in the Theme Testing Process article.

What Are Your Own Pet Peeves?

They say that you often learn from your mistakes and I’ll be the first to admit that during my time with WordPress, I’ve broken every one of these. But, like the rest of the development community, you learn and you begin building better projects with experience.

This is the first of this type of “WordPress culture” articles that we’ll be posting on the site… so share your own experiences below – or better yet, write about them at length and we’ll publish it if it’s great!

That said, this is certainly not the definitive list and I’m sure there’s more to add (we haven’t even touched hacking the core, harassing the database, or hard coding elements that should have options). Drop your own pet peeves in the comments!

What are some of the most annoying, harmful, or unsustainable practices that you’ve come across?