WordPress Coding Standards: A Guide for Developers

By . in WordPress. Updated on .

The reason that we have coding standards at all (not just for WordPress) is to create a familiar environment for programmers working on a project. WordPress in particular encompasses a wide variety of products. From the core itself to themes and plugins, there is a lot to look at – and a lot to get mixed up about.

If everyone formats their code the same way, uses comments, the same style of documentation and so on, working together becomes that much easier, and the learning curve of joining a new project won’t be as steep.

The need for cohesion in WordPress is magnified by the state in which the codebase is. WordPress does not follow a strict object-oriented approach and doesn’t use an MVC pattern. Projects that follow an OOP and MVC guidelines without exception (like Laravel) have consistency and best practices “baked in” due to their structure.

WordPress is unfortunately ripe for spaghetti coding, aka doing whatever you want. Best practices are difficult to enforce simply because products employing bad code may work just as well (on the surface).

By following the WordPress Coding Standards you can learn a little about the coding ethos of WordPress, create more WordPress-compatible products, show the community that you care and wrangle high-quality code.

More on Hongkiat.com:

Some Notes on the Standards

The standards do not define right and wrong. You may disagree with a rule, for example braces should always be used, even if they are not needed. The purpose of the WordPress coding standards is not to decide if you are right or wrong, it’s to decide how it should be done in WordPress.

The standards are not up for debate. Use of the standards is not the place to take a stand against an indentation style you don’t like. If something is in the coding standards then do it that way. WordPress developers will love you for it! That said, if you do not agree with something in there do raise your voice and let people know. It’s always possible to do things better but you should only change your coding style if the standards allow for it.

Consistency over anal retentiveness. If you’re in the last 10% of your project and you’ve just discovered that you’ve been using the incorrect naming convention for classes, don’t switch midway. In my personal opinion, I would rather read something consistently incorrect than something which is sometimes correct and sometimes not. You can always write a script to change things in one go, or read through your code at the end.

Following standards is difficult! Placing a brace on the same line as the function instead of a line below is pretty easy, even if you’re used to hitting enter before. However, when you need to think about 100 little rules, the whole process becomes a bit error-prone. Despite my tough stance on following standards, I am as guilty as anyone else in making mistakes. At the end of the day, incorrect indentation is not an irrevocable sin. Try your best to follow all the rules; you’ll learn everything in time.

WordPress Coding Standards

Right now WordPress has four guides, one for each major language used: PHP, HTML, JavaScript, and CSS. They form a part of a larger body of knowledge, the Core Contributor Handbook. Going through everything would take a while so I’ve highlighted some snippets from the four languages which I frequently see people getting wrong.

PHP

PHP is the main language of WordPress and is quite a loosely typed language which makes it ripe for regulation.

Brace Styles

Starting braces should always be placed at the end of lines. Related statements should be placed on the same line as the previous closing brace. This is best demonstrated with a code example:

<?php
if (condition) {
    // Do Something
} elseif (condition) {
    // Do Something
} else {
    // Do Something
}
?>
Generous Space Usage

I’m not a fan of squashed up code (I have bad eyesight) so this is one I particularly like to enforce. Put spaces after commas, and on both sides of logical, comparison, string, and assignment operators, after if, elseif, for, foreach, and switch statements and so on.

It’s easier to say where spaces shouldn’t be added! The only times you shouldn’t add spaces are when typecasting or referencing arrays.

A rather confusing exception to the exception is arrays where the array key is a variable, in this case, use a space. This example should make this clear:

<?php
function my_function( $complete_array = null, $key_1 = 4, $key_2 = 'bar' ) {
    if ( null == $complete_array ) {
        $final_array = $complete_array;
    } else {
        $key_1 = (integer) $key_1;
        $final_array[0] = 'this';
        $final_array[ $key_1 ] = 'is';
        $final_array[ $key_2 ] = 'an';
        $final_array['last'] = 'example';
    }
    return $final_array;
}
?>
Naming Conventions

This one can be hard to get used to, especially if you come from different environments. In a nutshell:

  • Variable names should be all lowercase, words separated with underscores
  • Class names should use capitalized words separated by underscores. Acronyms should be all uppercase
  • Constants should be all uppercase, separated by underscores
  • File names should be all lowercase, separated with dashes
Yoda Conditions

Writing conditions the other way around than you’re used to will prevent parsing errors. It looks a bit weird but it is better code.

<?php
if ('Daniel' === $name) {
    echo 'Write article you will';
}
?>
HTML

HTML doesn’t have that many rules associated with it; I could come up with quite a lot to make things more modular. There are only five rules you need to know when writing HTML:

  1. Your code must validate against the W3C validator.
  2. Self-closing HTML tags must have exactly one space before the forward slash (this is one I personally hate, but it’s a W3C specification, not just a WordPress pet peeve).
  3. Attributes and tags must be all lowercase. The only exception is when attribute values are meant for human consumption, in which case they should be typed naturally.
  4. All attributes must have a value and must be quoted (writing <input disabled> is not correct).
  5. Indentation should be achieved using tabs and should follow logical structure.
CSS

CSS is another loosely typed language, so there is plenty of work to be done here as well. Even so, the standards go pretty easy on coders.

Selectors

Selectors should be as qualified as necessary, be humanly readable, be all lowercase with words separated with dashes, and attribute selectors should use double quotes. Here’s a concise example:

<style>
input[type="text"],
input[type="password"],
.name-field {
    background: #f1f1f1;
}
</style>
Property Order

The standards recognize the need for some personal space here as they don’t prescribe a specific order for CSS rules. What they do say is that you should follow a semantic structure that makes sense. Group properties by their relationships or group them alphabetically, just don’t write them out randomly.

The largest cause for randomness is the “oh I also need to add a margin” and then proceeding to add it to the bottom. Take the extra .3 seconds and add the rule in the logical place.

  • Display
  • Positioning
  • Box model
  • Colors and Typography
  • Other
.profile-modal {
    display: block;
    position: absolute;
    left: 100px;
    top: 90px;
    background: #ff9900;
    color: #fff;
}
Value Formatting

This is one place where I particularly hate seeing inconsistencies. If you don’t follow the guidelines, that’s still better than sometimes seeing a space before the value; sometimes using shorthand, sometimes not; sometimes using units on 0 values, sometimes not, etc.

Value formatting is pretty complex but it does come naturally with some practice. Take a look at the exact guide in the Codex for formatting your values.

Javascript

In my experience, Javascript is most prone to going all over the place. While many developers know a considerable amount of Javascript it was learned gradually, as an afterthought to HTML, CSS, and PHP. When you’re just starting out with a new language you make a lot more mistakes and if those mistakes don’t cause fatal errors, they can become ingrained in you.

In many cases, the standards refer to a line limit or state “if a line isn’t too long”. This refers to the jQuery Style Guide which imposes a 100-character limit on lines. The WordPress guide is based on the jQuery guide, so it’s a good idea to give that a read as well.

Semicolons

This is the simplest rule but is one which is frequently overlooked. Never, ever, omit a semicolon just because your code will work without it. It’s just sloppy.

Indenting

Tabs should always be used for indenting. You should also indent the contents of a closure even if the contents of a whole file is contained in one. I’m not sure why but unindented top-level closure bugged me even before I read the standards.

Breaking lines

When breaking long strings, always break the line after an operator, don’t leave a variable hanging about. This makes it obvious at first glance that the line is broken and you haven’t just forgotten a semicolon.

Also, if a condition is long, break it into multiple lines and add an extra tab before it. This one looks very weird to my eyes but the separation it adds between the condition and the body is very visible.

<script>
if (firstCondition() && secondCondition() &&
    thirdCondition()) {
    var html = 'This line consists of ' + n + ' words, so it should be broken down after ' +
        'an operator';
}
</script>
jQuery Iteration

According to the standards, jQuery iteration (jQuery.each()) should only be used on jQuery objects. You should use basic for, for/in, while loops in Javascript for iterating over other collections.

Conclusion

There is a lot to note and keep track of, and there is no way someone can apply all this in one go. You should take your code as close as you can to the standards and work at following them exactly.

In my opinion, consistency is the most important rule. It is better to consistently do something incorrectly than to switch halfway. This is especially true with formatting practices since these don’t affect the functionality of your code and – for the most part – can be easily batch-changed later.

Do you hate an element of the coding standards, do you think something should be added? Let us know in the comments!

WebsiteFacebookTwitterInstagramPinterestLinkedInGoogle+YoutubeRedditDribbbleBehanceGithubCodePenWhatsappEmail