In the first post in this series, we reviewed some of the strategies that are available as it relates to organizing our WordPress theme directories in order to make them more maintainable.

Specifically, we touched on how to organize:

1. JavaScript and CSS files
2. Templates and Template Parts
3. Translations
4. Helper Files and Utility Functions
5. Third-Party Libraries

Ultimately, the goal was to provide a directory schema in which we could organize our files such that we would have a level of cohesion, understanding, and maintainability to the work that we're doing.

But that's not all there is to writing maintainable WordPress themes. Another is to follow the conventions set forth by the WordPress Coding Standards; however, this article is not going to be taking a look at the standards. The Codex does a fine job of that and we've covered them in another series.

Instead, we're going to take a slightly more granular look at some of the strategies and tools that we can use in order to make sure we're making our themes as maintainable as possible. In this particular post, we're going to look at strategies, then we'll wrap up the series by looking at some of the available tools.

Increasing Maintainability

As previously mentioned, it's one thing to have a logical way to organize all of the directories, files, and libraries that make up your theme; however, that's really only half of what goes into constructing a theme.

After all, there are predefined templates, functions, naming conventions, and tools all of which contribute to either making up the theme or to test to theme to make sure that it's not using any deprecated API calls and that it's compatible with the most recent version of WordPress.

To that end, I think it's important to understand each of these topics both as someone who is just starting out in building WordPress themes, and as someone who has been doing it for some time.

After all, there's never a better time to try to get better at what you're doing. Besides, the comments are also a great place to continue to the discussion to share alternative ideas.

But before we get there, let's actually talk about some practical things we can do as it relates to WordPress theming, and that increases the maintainability of what we're doing.

Templates

First, if you're not familiar with the template hierarchy, then I highly recommend you read the corresponding Codex page before continuing with this article.

In short, templates can be described as the following:

WordPress Templates fit together like the pieces of a puzzle to generate the web pages on your WordPress site. Some templates (the header and footer template files for example) are used on all the web pages, while others are used only under specific conditions.

Another way of thinking about it is this: When it comes to WordPress, everything that's displayed to the user is coming from the database. This includes the post title, post data, post categories, post content, comments, and so on.

Templates are the vehicles through which the information is presented to the user. They're composed of markup and PHP, styled via CSS, and may have some effects applied through the use of JavaScript.

But, assuming you aren't doing anything advanced with things such as custom post types and/or custom taxonomies (a topic for another post, really), then there's one unique thing about the WordPress Template Hierarchy that can serve as both a luxury and a problem of maintenance depending on how you look at it.

Note that in the linked Codex article, WordPress will have default index.php, header.php, and footer.php templates. The truth is, you can really get away with creating an entire WordPress theme by using only index.php.

Sounds kind of attractive, right? I mean, who needs to create so many different files when you can create a nice, small, lean theme that does everything you need it do.

But then think about this from the perspective of working with a team of either your own peers, of those who may be contributing to an open repository, or of those who may eventually pick up where you left off.

If all of the code required to render information from the database is contained within a single file, the odds that the complexity of that file increasing from its very creation are very high.

At the most basic level, we're looking at a single file with a number of conditionals, possible some switch statements and so on. And all of this is done because you've got to account for the archive pages, the single post pages, the single posts, the primary listing, and so on.

See what I mean?

But then, creating a separate files just to mitigate that complexity can be a beast all on its own. For example, let's say that you have single.php for displaying a single post and you have page.php for displaying a page and both of the templates have the exact same information except single.php has post meta data and page.php does not.

This is a prime example of when you may extract post meta data into its own partial, as we discussed in the previous article. Or perhaps you may extract the code responsible for rendering the content into its own partial.

Whatever the case may be, the point that I'm trying to make is that there is a balance to be struck when it comes with working with WordPress templates and the WordPress Template Hierarchy.

I don't think it's a good idea to use a minimal number of templates, but I also don't think it's necessary to use every single supported template if it leads to too much code duplication. There is a balance to be struck between templates and partials.

Ultimately, I think that the experience on how to use which comes with time, but having this frame of mind from the outset can help provide a level of organization and maintainability that's leaps and bounds ahead of where you may start having not done just a little bit of pre-planning.

Naming Functions

When it comes to working with functions and naming conventions, there are usually two rules of thumb to follow:

1. uniquely name your functions,
2. properly name them to indicate what will return data and what will echo data

But if you're someone who's just getting started in theme development, or you're someone who's looking to improve their skills in doing this, what does this practically look like?

When it comes to uniquely naming your functions, the reasons for doing this are so that you don't accidentally collide with a pre-existing function that's defined within WordPress or a plugin that may be running within your environment.

For example, let's say that you're going to be writing your own function that will filter the content before rendering it to the page. The correct way to do this is to obviously use the add_filter function; however, would you name your function the_content?

No, of course not. The reason is because WordPress already defines the_content. If you rename a function with that name, you're going to get errors. To that end, it's always best to prefix your functions with a unique key such as a the name of your theme or something similar.

So let's say that we want to prepend a signature to the end of our content, and let's say that we have a theme we're calling Acme. In order to do this, I recommend creating a function called acme_the_content because it identifies the name of the theme and indicates the name of the function to which it's hooked.

Let's say that you want to end each post with your name and Twitter handle. To do this, you may define this in your functions.php file:

<?php

add_filter( 'the_content', 'acme_the_content' );
/**
 * Adds a signature with my name, Tom, and Twitter handle,
 * @tommcfarlin, at the end of the post content.
 *
 * @since   1.0.0
 * @package Acme
 * @param   string    The original post content.
 * @return  string    The content of the post with my signature.
 */
function acme_the_content( $content ) {

    $signature = '<p class="post-signature">';
        $signature .= 'Tom | @tommcfarlin';
    $signature .= '</p><!-- .post-signature -->';
    
    return $content .= $signature;

}

It's relatively straightforward, isn't it? The short of it is that I try to use the follow format when creating my own hooked functions: theme_name-name_of_hook.

This makes it really easy to understand and follow not only when browsing the code but when viewing the functions that make up the theme or the file that's currently active in your IDE.

Returning and Echoing Data

As mentioned earlier, WordPress has another convention that it uses and that has to do with if information is going to be returned from the called function or echoed from the called function.

Luckily, this particular rule of thumb is really easy to remember:

• Functions that return data are prefixed with get_
• Functions that echo data are not prefixed with get_

You may find some anomalies, but that's the general gist of how the WordPress API indicates how it will be giving the data back to you once you've called the function.

In keeping consistent with our prior example, let's that that you want to echo the data when the function is called, then you would simply call the_content(); however, if you want to retrieve the content from a post, say, from within a custom loop, then you would call get_the_content() and store it in your own variable.

Perhaps something like this: $content_for_later = get_the_content(). Now you've read the data for the content that's currently related to the active post in The Loop and you've stored it in a variable that you can use later.

But knowing how WordPress names its functions for you is only half of it. After all, you're planning to build a theme or a plugin and want to make sure that you're keeping consistent with "the WordPress way" of doing things, right?

Case in point: In the example given above, where we filtered the content, we prefixed the function such that it was named acme_the_content, which indicates that the Acme theme is going to return the content from wherever it is called within the theme.

What were to happen if we were to name the function acme_get_the_content() ?

Well, technically speaking the function would still echo the data wherever it was called; however, it would be inconsistent with the WordPress API because the developer would be expecting the data to be returned to them such that they'd be able to store it in a variable or pass it to another function.

There's a mismatch between what the user expects to happen and what actually happens.

If we were talking about something in the real world, then this would be like having a switch on the wall for which the user expects that when they flip the switch, a light or a fan will come on in the same room when, in reality, perhaps nothing happens or a light or a fan in another room comes on.

To that end, we need to be careful with the naming of our functions so that we're not only writing functions that won't collide with other functions, but that are also clearly named, and that indicate how they will be handling the information when the function is called.

What About Helpful Tools?

As mentioned at the beginning of this article, there are also a number of tools and settings that we can install and configure in our development environment that will help us catch any potential problems before we end up launching our theme.

This means that we'll be able to identify functions that are going to ultimately be removed from WordPress so that we don't write out-of-date code. Additionally, we there are ways to know if variables we're trying to access don't have, say, indexes that are defined, or other similar features.

In the final article in the series, we're going to take a look at exactly that. In the mean time, review what's been covered here, feel free to share your questions and comments in the feed below, and then we'll look to wrap this series up next week.