In the previous post, I shared a little bit about the idea of separation of concerns – a concept that’s usually isolated to software development – and one way in which it can be achieved as it relates to working with WordPress templates.
But there’s always more work that can be done to help make our code as modular, reusable, maintainable, and readable (and any other buzzwords that I forgot ;) as it relates to programming projects.
One of the challenges of working in a system like WordPress is that it doesn’t necessarily promote practices that are typically seen in more classical programming environments, but – the way that I see it – we’re doing many of the same things:
- Solving problems through the use of code,
- Abstracting reusable components,
- Querying for information from a database through the use of provided APIs,
- Keeping areas of the code modular and related to the areas of the application and their best related,
- …and more.
After all, it’s all code, right?
Separation of Concerns: Queries and Helpers
Even if you haven’t done that, there’s a chance you’ve written helper functions to help process information prior to rendering it to the screen. Commonly, this is done within the context of actions and filters, but it’s certainly not limited to that.
To that end, there are ways that we can abstract our work to logically separate it, make the code easier to read and maintain over time.
Contain Your Queries
In the current state of WordPress, one of the most powerful classes (not the most powerful class, not the only class, but just an example) that we have at our disposal is `WP_Query`.
Of course, even if you’re not using that, there are a handful of other functions that allow you to construct a set of arguments for retrieving information from the database.
Anyway, it’s not at all uncommon to see larger queries written in the context of template files or some other type of view where the query is setup, data is retrieved, and then developers begin iterating over the data.
But this reduces the identity of your file because it prevents the file from having any clear purpose. That’s a Bad Thing.
Abstract Your Helpers
Similar to queries, it’s relatively common to write functions that help us process data prior to rendering it to the screen.
As mentioned, one of the most common ways that we go about doing this is through actions and filters, but those aren’t the only times in which we need to process information prior to displaying it.
And though it’s easy to know what an action or a filter (or, more generally, a hook is), it’s not necessarily easy for others to identify when certain functionality should be moved into its own function even if it’s not hooked directly to an event.
Case in point: Let’s say that we’re going to be retrieving a set of data from the database that’s in JSON format and we want to display it in an HTML unordered list.
First, it’s helpful to move the data retrieval code into its own function since it deals with a different part of the application than rendering data.
Secondly, the data could then be converted into some type of data structure – like an array – that makes for easy iteration.
And then, we can have the template run a `for` or a `foreach` over the collection rendering a list item for each of the returned values.
Easy enough, right?
Three Practical Steps
When it comes to doing this, there are a number of different strategies that developers may follow, and you’re likely to find a variety of different suggestions from different developers depending on the nature of their experience.
And I’m no different.
So if you’re looking for ways to start working towards separating your queries and your helper functions, then here are three quick steps you can follow regardless of the nature of your project.
Similarly, it’s helpful to create a directory that’s used to contain your queries, your helpers, and even your libraries.
For starters, I recommend creating an `inc` or an `includes` directory with your files primarily because it helps to indicate that other files are being included that help to power the project.
2. File Names
After that, I also recommend giving clear filenames. This should be a given, but naming a file something like `queries.php` isn’t always helpful.
Instead, consider something like `acme-user-queries.php`, `acme-taxonomy-queries.php`, `acme-json-helpers.php` or something like that.
Ultimately, the point is that you’re giving others – as well as yourself – a heads up as to what’s inside the file before you even open it (and if its worth opening it depending on the task at hand).
3. Code Comments
This is one of the points that I will probably reiterate over and over (and not just become I tend to over comment some of my own code).
I don’t believe that it’s possible to over-emphasize the importance of commenting code. No matter how clean you think it is, no matter how clever of a programmer you are, and no matter how simple or short a given function is, it’s still code and until our code is one-step away from the spoken word, then it’s going to need to be explained.
Parameters need to be explained, variables need to be explained, routines need to be explained, and how a function returns data when it fails to find data (let alone when it finds and returns data) needs to be explained.
Never assume that someone else can decipher your work – and that includes you six months from now.
Yes, There’s More
There’s always more that can be done, but if there’s low hanging fruit, then why not start doing it as soon as you get a chance?
The above three suggestions are things that I’ve found useful over time, but are not the only things that can be done.
There’s much more, but the ultimate point is to begin to think more strategically – more logically or modularly – about what you’re building as it will help to contribute to better organization, and even better commits (if you’re keeping your work open source).