WordPress Coding Standards

One of the reasons WordPress has triumphed is its open source nature: anyone can see the source code and contribute to the project… and not only on a technical level! In addition, the possibility of being extended through themes and plugins has also promoted the participation of third parties in WordPress (we are an example of this). But of course, allowing anyone to be involved has its drawbacks…

…one is the fact that each programmer has his own style of programming. For example, there’s the eternal discussion about the use of tabs or spaces for indenting the code, the naming conventions for variables and functions, how one should write conditional statements, and so on and so forth.

How can we get everyone to be on the same page? Is there a formula for all developers to follow the same rules and principles? Can we create a consistent and coherent project, when there’s thousands of people around the world involved?

What Are the WordPress Coding Standards?

In an article published in 2004 in SitePoint, the author explained clearly what coding standards are and why we need them. For example, imagine that you need to create a variable in PHP to store a username. How would you name it? $userName? $username? $user_name? And how would your teammate name it? I, for example, started programming with Java, so the most natural thing for me would have been to use “camel case” ($userName). Every time I saw something written with “snake case” ($user_name), it just looked so horrible!

Truth is, it doesn’t matter what option you choose—we are only talking about “styles” and here everyone has its own. As aforementioned, the problem appears when we have multiple developers working on the same project, each with its own style. If we want our project to be consistent, we need everyone to use the same one, or we can end up with a fragment like this:

where almost every line has its own style…

The Solution

The solution to the problem is to use coding standards. A coding standard is a simple document that defines the way in which developers have to write their code. If all developers follow the guide’s recommendations, we’ll make our project consistent in style and keep it from looking like a broken Frankenstein.

Typically, a good coding standard should:

1. Encourage developers to write intelligible code
2. Organize code in understandable working units (e.g. functions with no more than a certain number of lines, organization in paragraphs, etc.)
3. Define conventions for variable names, spacing style…
4. Describe how to comment the code

Defining a good coding standard is not easy. But after a little searching, you will soon discover that there’s plenty of guidelines in the Internet that you can use or adapt in your own projects. But here we’re talking about the WordPress world, and as an open source community we already have these guidelines defined. If you still do not know them, let me introduce them to you in a moment.

WordPress Has Several Coding Standards

The first thing that should have surprised you from my previous paragraph is that I have spoken of “guides”, in the plural. “How? WordPress defines multiple guides? Why?” Very good questions, my friend! ?  As you know, WordPress is a web project and, as such, it uses multiple technologies: PHP, JavaScript, HTML, and CSS. As a result, we have a coding standard for each of them: one for the PHP language, another for the code written in JavaScript, another for the layout of web sites in HTML and one for CSS styles.

It is not my intention to go into detail for each of them … more than anything because all the information you need is very well explained in the guides themselves. For each of the rules described there, you will find an explanatory example of what to do and what not to do. So you should have no problem following them. But I would like to highlight some of the examples that surprised me the most when I began to apply them.

WordPress Code is Shy and it Loves Its Own Space

I remember what impressed me most about the WordPress coding standards was the use of spaces. Until then, I was used to writing the code quite compactly:

But it turns out that in WordPress you need a lot of spaces:

And not only in PHP, but also in JavaScript (so that all code looks coherent, you know…):

If you are like me, you’ll think that “so much space is unnecessary”. But the truth is, when you get used to it, it’s hard to go back! These spaces help the code breath and look less overloaded, making it (in my opinion) more easy to read and understand.

Yoda Conditions

Another thing that made me laugh was the use of “Yoda conditions”. Usually, we are used to writing the conditions like this:

but the coding standard tells us to do it the other way round:

putting the literal first (in this case, an integer) followed by the variable. The reason for this small change is that if you mistype the comparison (i.e. one equal sign instead of two), the PHP interpreter would give a syntax error (you’re trying to assign a variable to a literal) and you could quickly identify  that something’s wrong.

By the way, if you ask yourself why it’s called “Yoda condition”, you just have to read this example and you’ll understand ?:

Write Code That Can Be Maintained

Remember when I told you that a good coding standard should promote intelligible code generation? WordPress is no exception. For example, in PHP you can write code like the following:

which is totally fine and compact. But, in comparison to this other one here:

it’s clear that the second version is much easier to understand, because it’s looks more similar to plain English. Whenever you are programming and you are in a situation where you must decide whether to write a code a little longer and “verbose” or a short and “hacky” alternative, opt for the first option: your future self or your teammate developers will appreciate it.

Watch Out! There Are Also Differences That You Must Remember

Finally, let me finish with a little warning. Although the creators of the coding standards have tried to make them as coherent and uniform as possible (remember the example of spacing in the parentheses), there are some differences between them. For example, while in the PHP guide they recommend writing the names in “snake case”:

in the JavaScript guide they ask you to do it in “camel case”:

This small difference between one language and another generates “curiosities” like the following:

When we want to pass variables from PHP to JavaScript we use the wp_localize_script function, which allows us to define an object with PHP values that we want to be available in JavaScript. In this case, we see how the array keys do not follow the guidelines we described for PHP. This is because these variables are intended to be used in JavaScript, not PHP.

Nelio A/B Testing

I was very impressed by the quality of this plugin, how easy it was to set up, and the outstanding support Nelio provides. I highly recommend Nelio A/B Testing.

Josette Millar

WordPress.org

View Plans

Let Your Editor Help You

Maybe you are thinking that the guides are great, but you do not have the time nor the desire to learn them. After all, it’s up to you, programmer, to apply them or not to your code, right? Well, you’re wrong! You can trust your code editor for it. ?

In a previous post, my partner Antonio talked you about Atom–an elegant and versatile code editor. Well, one of its advantages is that you can configure it to automatically check if the code you are writing follows the coding standards you indicate and, if it doesn’t, warn you so that you can correct it. Needless to say, this advice does not just depend on Atom. I, for example, use it in Vim, and surely you can also configure your editor for it.

Now it’s your turn, buddy. What do you think of WordPress coding standards? Do you follow them? Do you let your editor help you? Leave your opinion in the comments and let’s talk about it!

Featured Image by Glenn Carstens-Peters.