WordPress theme development tips

We’ve built multiple WordPress themes for our clients and have taken over many from other people/agencies; some good, some bad. The good ones don’t take much to get your head around how they’re structured and work, the bad on the other hand can sometimes make you want to go down the pub for a pint and wait for everything to blow over.

Although you may want to go down the pub, you need a challenge to keep your mind active and push your knowledge further. There may also be a diamond hidden in the dirt that the old developer knew about that you didn’t so do have a good look round.

Here are some practices that we follow for WordPress projects that don’t make you fancy a pint.

Code Style

We keep our code style consistent, this includes things like; deciding between tabs or spaces, camelCase(Upper or lower) or Delimiter-separated. For PHP we’d recommend going with PSR-2 as it is becoming the standard for a lot of projects. It also offers consistency between packages. IDEs have this built-in and can auto-format your code for you on save if need be, but if you prefer Sublime Text as your editor of choice then something like Phpcs will be your port of call to help manage your code style.

Code should be easy to follow and explain itself, if it doesn’t, we have comments explaining what we’ve done or what the code block does. When we write functions and classes, we add DocBlocks to them. This helps us remember what we’ve done in the future, and if anyone else joins you or takes over they’ll be able to see things at a quick glance. It also helps an IDEs intellisense give hints to you and any other developers using your code.

Take a look at PHPDocumentors DocBlock guides. If you want good examples of well-documented code then take a look at the Laravel framework, Taylor does an amazing job with it.

Another way to improve your coding styles when sharing with multiple developers as part of a team is to use EditorConfigs which most IDEs now support.

Plugin Dependencies

When we’re planning out our themes, we decide what plugins we’re going to be using that are available on the WordPress marketplace. We then use a PHP library called TGM Plugin Activation to help us manage the theme dependencies. Once we have the theme configured, the theme will automatically check for the plugins within the site itself; if they’re not present we’ll either be warned or the plugins will be downloaded and activated automatically. This saves us time if we have to deploy the theme to another of the client’s servers or set up a new environment.

DRY and KISS

Following the DRY (Don’t Repeat Yourself) and KISS (Keep it Simple, Stupid) acronyms makes our lives easier and stops us visiting the pub on a regular basis. If we see ourself repeating a block of code that doesn’t change or is used several times in multiple files, we move it to a function so we can keep the methodology consistent across our theme and don’t have any weird or unexpected bugs creep up along the way.

Keep it simple refers to the code you write, if it starts getting messy and hard to follow, take a step back, or even take a break, rethink the problem you’re trying to solve then refactor and improve.

Structuring your Code base

If you’re not careful the functions.php file of your theme can become a bit, well, big and bloated. We like to break our functions file up into different files and then require each one in the functions file, making it simpler to manage and update. Some examples would be as follows:

• Custom post types
• Widgets (Depending on quantity, maybe break it down more)
• Customizer
• Enqueue (CSS and JavaScript)
• Shortcodes
• TGM Plugin Activation (If you decide to use it)

As a side note if the shortcode isn’t inherently linked to your theme, consider moving it to a plugin to allow it to be used if the theme is changed or the community at large could benefit from it on the market place.

Plugin overload

There seems to be a trend with WordPress developers to always use a plugin if there is one. This can be a double-edged sword though, here’s why.

There are some very well known plugins like Yoast SEO, W3 Total Cache. If a plugin is popular and mature, by all means, use it. Plugins like this can do an excellent job and they’re actively maintained. It’s when you get to the lesser-known plugins that you really need to do your homework and be sure its the right plugin to use. There are some plugins that are infamous for not quickly fixing security issues that can leave your site exposed and vulnerable.

Sometimes if the theme is built to cover all possible bases, some plugins may not be needed as you could build the features into the theme; carousels and galleries being two big ones. We’ve had cases where a site we’ve taken over had a lot more plugins than were needed, some never used but activated. This can get worse if they’re out of date as it leaves the site more at risk to attack.

Cover your template hierarchy

WordPress templates have a hierarchy they follow, be sure to check all possible use cases. This is in case someone manages to get to some random page, it’s styled correctly and not broken. The hierarchy structure can be found here. WordPress also offer a Theme Unit Test to help you check each scenario. When we need to add custom templates to the theme we’re sure to give them clear and concise names, so if our client or use case need to create new pages in the future we know what template is likely to be used for what scenario.

Source and Assets

We use Gulp as our main build tool at the time of writing this article. With this, we put all of our source files into their own directory aptly name “source” or “src”, then have all the built files moved to the “assets” folder which we then use with our enqueue methods. This is our personal preference for handling our build tool, you may find something different works better for you. We find it also helps keep our root directory clean. Before the build tool runs we clean out our destination folders so that no stray files are left and potentially used in the future.

Enqueue scripts and styles

We enqueue all of our themes styles and scripts so we can take advantage of the features that WordPress offers in regards to enqueued styles and scripts. Where we use a build tool we only have to enqueue a couple of scripts but if you don’t have this in place yet, it’s worth checking out this often overseen functionality in WordPress.

The nice bonus to enqueueing is with each one you give it a specific ID which can be referenced later for your dependencies.

wp_enqueue_script('jqval',
        get_template_directory_uri() . '/assets/js/jquery-validation/dist/jquery.validate.min.js',
        array('jquery'), //Define jQuery as a dependency
        '',
        false);
        
   wp_enqueue_script('jqvalmethods',
        get_template_directory_uri() . '/assets/js/additional-methods.min.js',
        array('jquery', 'jqval'), //Define the dependencies of additonal methods
        '',
        false);

Version Control Systems

Always, always, always, use a VCS like Git or SVN. We use Git which helps us manage our work history. If we ever need to go back and look at what we’ve deleted or changed over time, it’s there readily available and easy to use. There is also a bonus if you store your repositories on services like GitHub or Bitbucket. These services will allow you to easily manage your repositories and any collaboration efforts you set up in the future. It also has the added safeguard of your work being saved in a remote location, so if your storage devices were to suddenly go to the digital heavens, your codebase would be safe and easily obtainable again.

Conclusion

We hope that you’ll be able to take away some new knowledge or some interest to check your own workflows. Any questions, or if you do something different you think may be of interest to us, get in touch on social media.

By: Jonathan Evans