The WordPress Coding Standards: Bringing It All Together

When it comes to writing a series of blog posts, one of the most challenging aspects as a reader is actually keeping up with every post that is published.

Even if you do manage to try and keep up, posts that are in excess of 1,000 words - especially those that include code - can take time that many of us don't have especially when it comes to juggling our work lives, home lives, hobbies, and other things.

So in order to make sure that the information presented throughout this series is still presented in a digestible way, I thought I'd experiment with doing a summary of the entire series. That way, for those of you who have missed an article or haven't had the time to sit down and go through each article, can still get the gist of each point mentioned throughout the articles.

With that said, let's take a look at everything we covered when reviewing the WordPress Coding Standards.

The WordPress Coding Standards

Generally speaking, the purpose of this entire series is to help bring light to the WordPress Coding Standards so that those who have not heard of them, those who are unaware of them, or those who haven't been following them are better equipped to write WordPress themes, plugins, and applications.

To do this, we took a deep dive into a number of different aspects of the Coding Standards throughout six different articles highlighting principles, best practices, and things to avoid.

Below, we've summarized each of the articles as well as the bullet points that are key points and worth noting for the topic in question. Of course, if you're left with wanting more information, you can hop back to the article in the series (linked at the top of this post) to read it in full.

1. Naming Conventions and Function Arguments

Naming Conventions

When you're working with classes, functions, variables, attributes, or arguments, naming conventions should help to explicate the purpose that they serve.

For example, classes are generally nouns and function names are normally verbs. Ultimately, it's about making sure the code is readable and maintainable.

Straight from the Coding Standards:

Don’t abbreviate variable names un-necessarily; let the code be unambiguous and self-documenting.

But this particular principle is is worth following regardless of where in the code you are working.

Function Arguments

Remember that when it comes to passing function arguments, it's important to remember that if a function name describes the action that it takes within the context of the class, then the argument should represent on what the function is actually operating.

Prefer string values to just true and false when calling functions.

This means that function arguments should be clear values - strings or numbers - as boolean values are often unclear and don't necessarily indicate what action the function will be taking.

2. The Use of Single Quotes and Double Quotes

When it comes to working with strings in WordPress, it's typically a matter of working within the nuances of PHP's string manipulation. As such, in this article, we reviewed how PHP handles quotes (both single and double) and how it affects our WordPress development.

Single Quotes

The easiest way to define a string in PHP is to wrap it with single quotes (that is, the ' character).

As with most programming languages, there are ways to escape characters so that you're able to write out a string literal. For example, if you wanted to write: "String's in PHP are easy," as a string, then you may do this:

'String\'s in PHP are easy.'

The backslashes will instruct PHP to write out the single quote rather than terminating the actual string. The second thing to note is that if you have a variable, it will not replaced when quoted in single quotes.

Double Quotes

Double quotes operate a bit different within PHP. Specifically:

If the string is enclosed in double-quotes ("), PHP will interpret more escape sequences for special characters.

This means that if you embed a variable within a double-quoted PHP string, then the variable will be interpreted and its value will be inserted in place of the variable prior to displaying it to the screen.

Strings and WordPress

Since much of the work done in WordPress also includes writing out markup within a PHP string, it's best to place those strings in single quotes so that the attributes of the HTML element can be enclosed in double quotes.

But there are times where it's more preferable to use double quotes especially when you need to evaluate a variable.

The best advice that can be offered here is to know how single quotes and double quotes work within PHP, and then use them appropriately based on your use case.

3. Indentation, Space Usable, and Trailing Spaces

Remember: White space enhances readability of code and, as developers, one of our primary goals should be to make sure that the code we're writing is not only following a predefined standard, but is also catering to other developers for ease of readability and maintainability.

Indentation

As far as indentation is concerned, there's nothing really new especially if you're familiar with C-style languages. Most of the time, you'll indent each time that you start a new block.

Your functions will be indented within the class
Your conditionals and switch/cases and other blocks will be indented within their functions
Your loops will be indented within their functions, within their conditionals, and so on

Note that the Coding Standards do have rules on tabs and spaces:

Your indentation should always reflect logical structure. Use real tabs and not spaces, as this allows the most flexibility across clients.

This is especially useful in the open source community.

Space Usage

Spaces should be placed in the following places:

After commas
On both sides of logical operators (that is, ||, &&, and !)
On both sides of comparison operators (that is, <, >, ==, ===, etc.)
On both sides of assignment operators (namely =)
On the both both sides of the opening and closing parenthesis of functions, conditionals, loops, and so on.
When a variable is being passed as an index of an array, but not when a literal value (such as a string or an integer)

Trailing Spaces

This is one of the simplest conventions to follow. Honestly, chances are good that your IDE or editor of choice has this feature built-in, or there is a plugin available that will allow you to automatically do this.

If not, you should be able to activate the ability to see tabs, spaces, carriage returns, and so on so that you can easily identify where the trailing spaces are. And when you see them, eliminate them.

4. Brace Style, Regular Expressions, and PHP Tags

In this section, we took a look at why style matters. We also defined exactly how coding standards and conventions define how we style our code.

Brace Style

Generally speaking, the rules are simple:

Single line blocks can omit braces
Multiline blocks should always include braces
When you have excessive multiline conditionals, consider breaking up the conditionals into their own functions to minimize the block

These are particularly common if you're coming from other C-style languages; however, just as WordPress has subtle nuances that other languages do not, it's worth highlighting them here.

Regular Expressions

PHP offers a variety of ways to work with regular expressions, though WordPress recommends that we only use a handful of the available functions.

The rules for working with regular expressions in PHP in WordPress are as follows:

Use the preg functions that PHP offers
Do not use the \e switch that is offered by PHP - use preg_replace_callback instead.

Specifically, I recommend being familiar with the following functions:

Additionally, note that preg_replace_callback is a way to call a function when a regular expression has found a match.

PHP Tags

There is a very simple rule of thumb for using PHP tags within WordPress development:

Never use shorthand PHP tags

This means that you should never open a file or an inline PHP statement with <? or with <?=. Naturally, all inline PHP statements should be terminated with the ?> closing tag.

In addition to the coding standard that is defined above, I'd also add:

Avoid adding a terminating PHP tag in pure PHP files.

The reason for this was mentioned verbatim in the associated article:

But if you're writing a plugin or an application file that's 100% PHP, then there's no need to add a terminating tag at the end of the file. The parser will be able to detect it itself, and if you do include a terminating tag, then you can potentially have whitespace left at the end of the file that can calls all sorts of problems when it comes time to activate the plugin.

5. The Ternary Operator and Yoda Conditions

When it comes to writing WordPress-based code, the Coding Standards say that we should strive for readability:

In general, readability is more important than cleverness or brevity.

Some developers consider the ternary operator to be a bit at odds with this particular principle specifically because it's yet-another-way of writing an if/else statement. Even still, the ternary operator is a viable option when it comes to writing simple conditionals and is stated in the WordPress Coding Standards.

The Ternary Operator

First, for those who are not familiar, the ternary operator is a simplified way of writing an if/else conditional statement. It's typically used only when the conditional is of the simplest form and only when there is a single if and a single else block.

$uses_gasoline = 'hybrid' == $car_type ? false : true;
echo $uses_gasoline;

An important thing to notice: the ternary operator is testing for true (rather than false, obviously).

Yoda Conditions

Yoda conditions refer to the reversal of variable to value comparisons that we perform when writing WordPress code. We this, according to the Coding Standards, because:

In the above example, if you omit an equals sign (admit it, it happens even to the most seasoned of us), you’ll get a parse error, because you can’t assign to a constant like true. If the statement were the other way around ( $the_force = true ), the assignment would be perfectly valid, returning 1, causing the if statement to evaluate to true, and you could be chasing that bug for a while.

Sure, it's debatable, but it is part of the standard and you are going to see this used through WordPress core, themes, plugins, articles, and more.

6. Database Queries and Formatting SQL Queries

So, in short, if the API falls short of what you need, then $wpdb may be your best option, but I recommend only using it if you've exhausted the rest of your options.

Database Queries

In WordPress, there are a number of APIs that make it possible for us to craft our own queries without needing to write SQL. Some of these APIs include:

It's important to familiarize yourself with what the API offers so that you're able to know whether or not there's a function or an object available to use before to jump right into writing your own queries.

SQL Queries

APIs can't predict all cases in which we need to write our database queries. And in those situations, WordPress provides an object that allows us to directly interact with the database: $wpdb.

It allows us to:

SELECT variables, rows, columns, and generic results
INSERT rows
UPDATE existing rows

And allow us to retrieve the data in a format that we'd most like to work with: an array, an object, or a single value (in some cases), and even allows us to protect ourselves through SQL injection.

But remember:

If you must touch the database, get in touch with some developers by posting a message to the wp-hackers mailing list. They may want to consider creating a function for the next WordPress version to cover the functionality you wanted.

Conclusion

As I mentioned earlier, it can be tough keeping up with a series of articles, especially those that involve code. To that end, I wanted to experiment with providing a summary of the series that still gives enough information to those who haven't had a chance to keep up with the entire series, but who are still interested in the topics at hand.

So if this particular strategy or type of article is something that you enjoy, let me know and perhaps we can continue do so for other series; otherwise, no harm no foul - I'm fine either way.

Regardless, I hope the series has helped explicate a number of different areas of the WordPress Coding Standards that you've either previously missed, misunderstood, or haven't fully grokked until reading these articles.

HIGHLIGHTS OF THE DAY