Making the Perfect WordPress Theme: How to Code Well

In the previous part of this series; we went through various WordPress APIs that we should learn about, talked about the importance of making a theme translatable (or even better, releasing them already translated into other languages) and understood the concept of licensing themes and using licensed products with the themes.

In this article, we're going to focus on code: We'll see how to code with WordPress coding standards, how to properly comment our code and how to validate and test the theme.

WordPress Coding Standards

Yes, I know, you have your own preferred style of coding: you like to compress a big function with a single line of code, you don't like whitespace that much - Ah, I was once just like that.

But if you're going to develop for other people and literally sell your code, you have to make your code understandable. And while you may think that your code is "clear enough", there are universal standards for coding to help everyone code with the same style, and all serious theme marketplaces and download centers (from to ThemeForest) require you to code with standards.

There are four main programming and markup languages needed to develop WordPress themes: HTML, CSS, JavaScript and of course, PHP. Let's have a look at each:

HTML Standards

There are relatively simple rules for writing standards-compliant HTML code:

  • Validate your code with W3C. Always. We'll come to that later.
  • Be careful with self-closing elements: You have to end the element with a space, a slash and the "greater than" sign.
  • When typing attribute values, type them all in lowercase - unless it is for humans.
  • Always wrap your attribute values with quotes. Both single and double quotes are acceptable.
  • Indentation must be logical and readable. PHP code mixed within the HTML shouldn't be an exception.

Check out the WordPress HTML Standards page at Make WordPress for more information.

CSS Standards

The list is a bit longer, but again, there are easy rules for proper CSS coding:

  • Properties should be indented with tabs.
  • You can group selectors but every selector must have its own line for readability.
  • Name all your class and id selectors with lowercase letters and don't forget to separate words with hyphens.
  • Use readable selectors. .c6 is not a good name - name it .column-sixth!
  • No overqualifying. div.column is meaningless when you can just use .column.
  • Properties and their values should be in lowercase too, except for font names and vendor-specific properties.
  • Ordering for the properties needs to be "display, positioning, box model, colors, typography and other".
  • You should also order the vendor prefixes from longest (-webkit-) to shortest (no prefix).
  • Keep your media queries at the bottom of your stylesheet.
  • Comment your CSS code as you comment in PHP. More on that later.

See the WordPress CSS Standards page at Make WordPress for a more detailed explanation.

JavaScript Standards

Since nowadays JavaScript is becoming crucial for many WordPress themes, we need standards and rules for it, too:

  • Braces can not open and close within the same line.
  • Prefer single quotes over double quotes, unless a string contains single quotes.
  • You're free to use whitespace as you please in your code - don't use whitespace on blank lines, though. And don't forget that you're using whitespace for readability - not for fun.
  • Name your functions and variables using camelCase, not_with_underscores. Constructors should be in TitleCase.
  • You can declare multiple variables on a single line; but if you're going to assign values, you'll need separate lines.
  • The new Array() and new Object() notations are "no-no"s. Use shorthand equivalents ([] and {}) instead.
  • Treat conditionals and loops very delicately - they're usually the easiest to misread. Using braces and whitespace are key to this.
  • If you're going to use jQuery; define an anonymous function, and pass jQuery as the argument before doing anything else. Check the example to make sure.

The WordPress JavaScript Standards page at Make WordPress has more information, bookmark this page and use it.

PHP Standards:

This is the more difficult part. There are tons of rules to consider:

  • Naming conventions
  • Single and double quotes
  • Whitespace usage
  • Regular expressions
  • "Yoda Conditions"
  • Special guest star SQL and formatting database queries

If you don't know what they are, then maybe your best course is to tread lightly.

There are two awesome resources for you to learn it, though:

  1. WordPress PHP Standards page at Make WordPress
  2. The Wptuts+ series called "The WordPress Coding Standards" by Tom McFarlin

Properly Commenting Your Code

In order to let other developers understand how you made your theme, you need to make your theme code clear and readable - and this requires commenting your code.

The best practice for PHP is to use PHPDoc, the documentation style of phpDocumentor. It's widely used between WordPress developers and recommended in the PHP Documentation Standards page at Make WordPress. It provides a clean documentation style for your PHP code.

As for CSS, the WordPress CSS Standards page at Make WordPress recommends you to do it like PHPDoc, along with a couple of other suggestions.

As for your HTML and JavaScript code, it seems that there's no recommended or required way to comment your code, but this doesn't mean that you don't have to do anything: Try to be as clear as possible with your code and provide little bits of information by commenting anywhere you find necessary.

Validating and Testing the Theme

The theme may be working as a neat website in your head, but hopefully, there will be hundreds (maybe thousands) of people that will get to use your theme and be sure that they will try to make websites that you can't possibly think of. Plus, there are requirements for theme marketplaces and theme directories for you to pull your theme together.

That's why you have to test your theme and validate your code. I have three ideas for that:

Validate your HTML & CSS with the W3C Validators

The first thing you need to do is validate your code with the validation services of the W3C. Both the HTML Markup Validator and the CSS Validator services are used and developed for years and they're the best validation services available.

After you do the two things below, simply check the demo pages with these two services to make sure there are no errors or warnings.

Use the "Developer" Plugin to Correct Your Theme

Developer is a free plugin developed by Automattic which, in their words, help WordPress developers develop. It's actually just a plugin installer: The main purpose of the plugin is to provide the essential plugins for your development environment.

Developer suggests 16 various plugins. While some of them make your development process a lot easier (like User Switching and Theme Test Drive), some of them help you debug your theme (like Log Deprecated Notices and Theme Check).

The ones I find the most useful are Theme Check, Theme Test Drive and Debug Bar but all 16 plugins provide great features. I suggest that you install all of them to test the heck out of your theme.

Test Your Theme With Test Data

You can't just code the theme and say that it's completed - you have to test it with some content. You can create your own content but you should consider testing with some "test data":

  • Use WordPress' sample data. This sample data contains some of the most used content types and will help you notice your theme's shortcomings against content you forgot to consider.
  • Use more exhaustive test data. is a little website with a scary collection of sample WordPress content. I'm not kidding: From menu items that go 10-level deep and Amazon Store embeds, this is the most exhaustive test data I've ever seen. I never tested a theme with this sample content but if you succeed to make your theme work with this data, you probably don't have to worry about your theme looking dull in any scenario.

The only downside of these two tests is you won't be able to test your content with shortcodes or the type of specific content you had in mind while developing the theme. I suggest that you test the theme with at least WordPress' sample data, then create your own content. After all, you're going to need solid content when you create the demo website for your theme.

Wrapping Up

In this article; we went through the processes of properly coding and commenting with some standards, then we saw how to validate our code and test our theme. In the next part of the series, we'll be looking at some bad practices.

Stay tuned and don't forget to share the article, if you liked it!



Related Articles