Building Quality Into WordPress Projects: APractical Example

One of the best things about learning a new skill in software is that you often undergo this process of getting something working, learning about a few of the mistakes you've made, refining the code, and then repeating the process.

Ultimately, it's about improving the quality of what you're doing such that the end result is better than it would've been had you just left it as it were in its first iteration.

And, really, when it comes to writing software, one of the things that we often hear and often talk about is quality. More specifically, we talk about building quality into our software. 

But my guess is if you ask ten developers what quality means to them, you would get ten different answers.

The word "quality" offers three definitions:

1. How good or bad something is,
   
   


2. A characteristic or feature that someone or something has : something that can be noticed as a part of a person or thing,
   
   


3. A high level of value or excellence.
   
   

If you think for a moment how this relates to the products that you build using WordPress, what comes to mind?

• Is it the organization of the files that compose your project?


• Is it how well your code conforms to the WordPress Coding Standards?


• Does it have to do with how well you've followed best practices of the paradigm you've chosen?


• Maybe it's all the above; maybe it's something that is not listed. 

Whatever the case, "quality" can mean different things to different people. But I believe there are certain things that aren't subjective with regard to WordPress development.

Quality and WordPress Development

Before going any further, I'd like to note that when quoting someone else, unless it's a well-known source, I like to keep the source anonymous.

The reason is that I don't want people who read tutorials like this to get side-tracked and try to take issue with what the person has said. It's beside the point, you know?

And that does happen. I'm speaking from experience.

With that said, recently someone approached me about a bit of code that I had provided about working with WordPress hooks when building themes. In short, they said:

Saying more lines of code is better than less is something only a hard-core, seasoned WordPress developer would say. The less code, the better.

For hobbyists and those who are just learning the ropes of development, I can see how this would seem true. For those who have been working in the field for a while, you likely recognize the problem with this.

I'm not claiming that more code is always better code. It's not. Instead, I am suggesting there are times where an entire function is better than a single line of code.

How do we build this into our own work? How do we convey this to those who are less experienced programmers? Let's take a look at a concrete example and see if there's something to glean from it.

An Example: How Filters Yield Quality

In WordPress 4.4, support for title tags changed such that you add support for it by simply including the following line in your functions.php file:

<?php add_theme_support( 'title-tag' ); ?>

If you don't want to use that function, you're going to be required to hardcode the title element into the header template of your theme. 

Of course, there are plugins and themes that have not yet been updated (at the time of this tutorial). To that end, it's still relatively common to see something like the following line of code in template files:

<title><?php wp_title( '' ); ?></title>

But why would anyone mess with the title? Think of SEO plugins. They will often alter title elements to be more search-engine-friendly.

Let's take a look at a real-world example: Say you're working on a theme and its title element includes a call to wp_title. Further, you want to make sure that wp_title is filterable so that other code like the aforementioned plugins can update it.

It seems straightforward enough, right? But let's say you want to dress it up a bit by including a separator and updating its position. In this case, you may do something like this:

<title><?php wp_title( ‘|’, true, ‘right’ ); ?></title>

Or maybe you want to take it a step further and introduce the name of the blog and its description. Or maybe you want to set up the title so that it's different on the homepage. 

Then you may do something like this:

<title><?php bloginfo('name'); ?> | <?php is_home() ? bloginfo('description') : wp_title( '' ); ?></title>

In isolation—outside of any plugins or other work—this looks fine. It's a single line of code that hobbyists can use to achieve their ultimate goal.

But what happens when someone distributes the theme? Furthermore, what happens when someone wants to use a plugin to alter the title element?

It won't work.

This is but one reason why less code is not always better code and why less code can be of lesser quality.

More Code, More Quality

To make sure that the use of wp_title() is as flexible as possible, we need to define a custom function and filter it using the wp_title filter provided by WordPress:

<?php

add_filter( 'wp_title', 'acme_wp_title', 10, 2 );
/**
 * Provides a standard format for the page title depending on the view. This is
 * filtered so that plugins can provide alternative title formats.
 *
 * @param       string    $title    Default title text for current view.
 * @param       string    $sep      Optional separator.
 * @return      string              The filtered title.
 * @package     acme
 * @version     1.0.0
 * @since       1.0.0
 */
function acme_wp_title( $title, $sep ) {
    global $paged, $page;

if ( is_feed() ) {
return $title;
}

// Add the site name.
$title .= get_bloginfo( 'name' );

// Add the site description for the home/front page.
$site_description = get_bloginfo( 'description', 'display' );
if ( $site_description && ( is_home() || is_front_page() ) ) {
$title = "$title $sep $site_description";
}

// Add a page number if necessary.
if ( $paged >= 2 || $page >= 2 ) {
$title = sprintf( __( 'Page %s', 'acme' ), max( $paged, $page ) ) . " $sep $title";
}

return $title;

}

The code above is obviously more code than the single line in the previous example, but it's also more flexible.

First, the code checks to see if the page is rendering in an RSS feed. If so, it only returns the specified title. Otherwise, it then appends the name of the title to the specified $title string. When viewing the homepage or front page, the code places the description after the separator.

Finally, if the user is paging through the site, the code prepends the page number to the separator and title.

This provides the base functionality for rendering the title element within the theme. This is not the default way to do it for all themes, but it's arguably a better way to do it. 

As such, you can also customize this function to fit whatever you believe is best for your own work.

This Is Quality?

The key takeaway of this tutorial is not how to set up a filter for titles, or how to set up filters, nor is it how to handle titles. Besides, wp_title is being deprecated, as mentioned earlier in the article.

We end up with a customized version of the title. We also give third-party developers the ability to override our own code.

Though this is more code, it's a higher quality solution.

Conclusion

Remember, though: That's not always the case. Sometimes more code can reduce quality and it can increase the complexity. But that's not the point of this article. Perhaps it's best discussed in another tutorial.

Instead, the purpose of this tutorial is to show how less code may result in lower quality and how more code may improve quality. But this isn't a hard and fast rule. Nor is it supposed to be.

Instead, the intent is to introduce a mindset of thinking through what defines quality. Sometimes, less code is quality code; sometimes, more code is quality code.

When working on your project, don't look for ways to consolidate code just for the sake of less code. Look for ways to write code so that it's elegant, extensible, readable, and maintainable, and above all fit for purpose. 

All the above together help contribute to quality.

If you're looking for examples of other WordPress projects that can be used to examine code quality, to use in your work, or in client projects, you may also find something interesting in the marketplace.

If you're interested in other things I've written or produced for Envato, you can check out my work on my profile page, and you can follow me on my blog and/or Twitter at @tommcfarlin where I talk about software development in the context of WordPress.

Don't hesitate to leave any questions or comments in the feed below, and I'll aim to respond to each of them.