A Newbie’s Guide to WordPress Coding Standards

The real beauty of WordPress is that it’s open-source. Because of that, you can contribute to it and make it even more awesome. Yes. You..

While there is a definite business side to open-source software, the philosophy behind it is simple: let’s make something together. If you’ve ever worked with a group of any kind, you know how hard it can be to make people check their egos at the door and play nice.

So the Powers That Be wrote up the WordPress Coding Standards, a collection of HTML, CSS, JavaScript, and PHP rules guidelines written specifically to keep the source code as clean and functional as possible.

Get it…functional? It’s a code joke.

Why Do We Need WordPress Coding Standards?

My writing style is casual, off-the-cuff, and full of puns. My wife’s is collected, professional, and concise. Yours is…something altogether different and unique, too. None of them are bad or wrong, just different.

That applies to code as well. My HTML will look different than yours, my JavaScript may make your eyes bleed, and your CSS might be life-changingly beautiful.

Despite code’s prescriptive syntax, what you and I write line-by-line will be a little different. The WordPress coding standards are there to make sure that everyone who comes after you and contributes to the code is able to not only read and understand your work, but can also seamlessly add their own to it.

What Do You Need to Know to Contribute?

The first time you look at the standards, they might seem pretty restrictive. And they kind of are. If they were more lenient, they wouldn’t do their job, and the core WP code would be a mess.

But the documentation is so comprehensive, you don’t have to remember every detail. Just look it all up as you need it, referencing each section as you parse and debug your code before your final pull request is accepted and merged.

If the term pull request is foreign to you, check out our beginner’s guide for git and Github newbies. You’ll definitely need to be familiar with git because the WordPress code lives on Github.

Examples of the WordPress Coding Standards

Each of the core languages that make up WordPress has its own standards: PHP, JavaScript, HTML, CSS. If you’re truly dedicated to the cause, you may eventually contribute something with all four of them.

If you aren’t at the point where you can feel as though you are able to contribute, that’s okay, too. Looking at and learning the gist of the coding standards now will make your life a lot easier when you are ready.

HTML Examples

Have you ever opened up a web page, checked out the source code, and then cringed at how anyone ever thought writing that code was a good idea?

Me, too.

That’s why the HTML standards are set up the way they are. Just behind the W3C standards themselves, these are the standards you should commit to your fingers’ muscle memory.

Indentation

Outside of braces, indents are one of the most contested elements of most code. The WordPress Codex says to use tabs and that you must indent your code so that open and closing flags line up. Note: This took me a long time to get used to, as I am strongly in the ‘you indent with two spaces’ camp. If you are, too, you have my sympathies.

Good:

<h1>Hello, World!</h1>
    <div>
        <p>Ahoy, Divi Nation!</p>
    </div>
<h2>Goodbye, World!</h2>

Bad:

<h1>Hello, World!</h1>
<div>
<p>Ahoy, Divi Nation!</p>
</div>
<h2>Goodbye, World!</h2>

The same logic applies when you’re mixing PHP and HTML flags.

Quotes

Use quotes. Don’t not use quotes. Double or single is your choice, but use them at all costs. You have been warned.

Good:

<form>
Your Email Address: <br />
<input type='text' name='email'><br />
<input type='submit' value='Submit'>
</form>

Or

<form>
Your Email Address: <br />
<input type='text' name='email'><br />
<input type='submit' value='Submit'>
</form>

Bad:

<form>
Your Email Address: <br />
<input type=text name=email><br />
<input type=submit value=Submit>
</form>

So…quotes = yes. No quotes = bad.

For the rest of the HTML Coding Standards, you can go here.

CSS Examples

When it comes to CSS, most of the standards are for readability. There are a lot of classes and ids in WP. If we’re not careful, these stylesheets can turn into a real nightmare.

Structure

The WordPress coding standards say that CSS needs to have every single element on its own line, from class and id selectors to the styling and braces themselves. Additionally, you must use specific names for your elements that others can follow.

Good:

#email-div-about,
#email-div-blog {
    text-align: center;
    display:block;
    margin: auto;
}

Bad:

.awesome-emails, .amazing-something { text-align: center; display:block; margin: auto; }

or even this:

.awesome-emails,#amazing-stuff {
    text-align: center;
    display:block;
    margin: auto;
}

You can see that it the WP way of writing CSS makes each element easier to identify and style.

Properties

Just like the structure and selectors, properties need to be as concise and specific as possible. This make other users’ lives a little easier, and it also brings the overall size of the code down — and when the repo is as expansive as the WP, every bit and byte counts.

Good:

#form-submit-btn {
    display: block;
    background: #000;
    color: #fff;
    margin: 20px;
}

Bad:

#bjs-awesome-button {
    background: WHITE;
    color: #FFFFFF;
    border: 35PX;
    Margin-right: 30;
}

The second one is just ugly. And not in the awww, that dog is so ugly it’s cute kind of way.

And there are a ton more CSS standards to check out, too.

JavaScript Examples

There are a lot of important JavaScript WordPress Coding Standards. They are not that hard to remember, or really that far away from typical JS best practices, but there are enough that you should familiarize yourself with them.

Variables

What would JavaScript be without variables, you know? You can’t do much of anything without good ole var, and that’s what I want to make sure you do right. By following the official guide, you’re going to avoid weird scope issues that affect different parts of the repo than you mean to.

Good:

var b, j, k, awesome,
    // You should indent with tabs here, too!
    value = ‘Something’;

Bad:

var b = true;
var j = false; // since it’s a bad example, here’s a comment done wrong!
var k = b + j;
var awesome = true;

Comments

Okay, so maybe comments aren’t specifically a part of the JavaScript code itself, but I am a comment junkie and think that well-documented code is an art. The Core team has put together some great guidelines for commenting that make me smile.

Single Line:

function bjk();
//Be concise and explain the next line of code
$( ‘beej’ ).beAwesome();

Multiple Lines:

/*
 * Make sure that you keep the asterisks
 * lined up when you put comments on
 * multiple lines. Like this!
 */

Inline:

These will only be used to annotate parameter lists.

Function bjk( param1, param2, param7 /* explain why I skipped params 3 to 6 */, param 8 ) {
    // fantastic code goes here
}

Now you can annotate with the best of them.

And while you’re at it, you should probably read through the entire slate of WordPress coding standards for JavaScript.

PHP Examples

WordPress is PHP software. Devs and contributors are adding bunches of JavaScript in there these days, but it’s still predominantly PHP.

PHP Tags

Opening and closing PHP tags should be on their own lines (again, for readability), and you should never, ever, ever shorthand them. Ever.

Good:

<div>
    <?php
        echo ‘Hello, world!’;
    ?>
</div>

Or

<div>
    <?php echo ‘Hello, world!’; ?>
</div>

Bad PHP:

<div>
    <?
       echo ‘Hello, world!’;
    ?>
</div>

Naming Conventions:

PHP can do so much. So much. But it’s also kind of a mess. It was because of PHP that I first discovered the term spaghetti code, and if you follow the WordPress coding standards, maybe you can help clean things up by naming things the right way.

• functions are in snake case: function_name
• Classes are in snake case, but with capital letters: Class_Name
• Unless the class is an acronym, then it’s all-caps snake case: WP_JS
• Constants are also in all-caps, snake case: CONSTANT_NAME
• files are written in all lowercase with hyphens: wp-config.php
• functions are in snake case: function_name

Those are the simplest standards you’ll need to learn to contribute to the WordPress PHP codebase. The others are, once again, found in the codex.

How Can You Contribute?

Once you’re familiar (enough) with the baseline standards, you may want to read up on how to actually get into the contributor community.

Probably the best is make.wordpress.org because that’s where they (wait for it…) make WordPress.

Everything from documentation, core, support, to design, to all the coding languages have regularly scheduled Slack meetings you can jump into freely and immediately.

Additionally, there are WordCamp contributor days and panels. At WordCamp US 2017, after the main part of the conference, folks gathered for sessions that were specifically put together for people to contribute. Other camps will have similar offerings. If you’re interested in getting involved, I strongly suggest talking to and meeting some of the people who are already contribute.

Between forums, Slack, contributor days, and the unbelievable amount of documentation available in the WP Codex, you should have no trouble making sure that your code can win the Prettiest WordPress Code Award.

So get out there, codejunkie! And remember, we say code is poetry for a reason.

PS: we need real award like that to give out — a trophy or sash and tiara or something to give away at the national WordCamps for prettiest code contribution that year. Let’s make this happen, people!

Article thumbnail by Maksim M / shutterstock.com