Get out of my way!
A lot of code that I try and interact with does not get out of my way.
I write this not for how to write code for users — those that will install, activate, and be done. I write it for the rest of us, the minority, the very few. We are your smallest contingent and potentially your biggest evangelists. We are few but we do matter.
We are People That Make StuffTM. And we need your plugin and theme code to get out of the way.
This is a more common understanding in MVC-centric frameworks, where the view is always separate from logic. Tom McFarlin has good practical reading on MVC and WordPress on his blog.
WordPress meshes views and logic a good bit, but it doesn’t mean WordPress core and plugins shouldn’t have options for view-less data retrieval.
What do I mean? Let me use an example from WordPress core.
If I want to get a list of terms attached to a particular post, and I want to create custom output for those terms, what do I do? I use get_the_terms(). Easy peasy.
The return data is simply an array of term objects that we can manipulate as we see fit.
Now, it’s nice to have some functions lying around to help us create some common markup for showing these terms. That’s why core has a function like get_the_term_list(). get_the_term_list() is a very simple wrapper of get_the_terms() that outputs the terms in a common manner, with some basic options. Here’s the entire code for it in core:
[gist id=”60b8ce2a3224de32b04b” file=”get_the_term_list.php”]
If you’re going to manipulate data that shows posts, you want the most basic data you can get. That’s why it’s nice for get_the_terms() to be unassuming. It doesn’t have an opinion as to how we display the data. That’s what the helper functions are for.
Both the simplicity of the data returned and the helper functions above can go many layers deep. For instance, in WordPress core, get_the_tag_list() is a helper function that wraps get_the_term_list().
[gist id=”60b8ce2a3224de32b04b” file=”get_the_tag_list.php”]
In another direction, we can have a helper function that echoes the list of terms:
[gist id=”60b8ce2a3224de32b04b” file=”the_terms.php”]
Are these all necessary? Maybe not.
Determining how many layers of helper functions to create depends on your plugin or theme, and how you anticipate developers may use your code. But it’s important to consider what developers may do with your code.
For front-end facing code, these issues can be especially important. There are all sorts of ways people will want to display data they retrieve from your plugin. Generally, I think we can determine some good rules to follow for such code:
- Have a version of the code that doesn’t assume output.
- Have a version of the code that is return only, and doesn’t echo.
- Have a version of the code that echoes the output (probably with a filter as well).
The last thing I want to see when I’m working with a plugin, is that there is code that does what I want, but assumes too much about how I want to do it.
I just ran across this with a related posts plugin. The plugin has a function to retrieve related posts, which is great! Unfortunately, it didn’t GoomWay, and it assumed not only markup, but also CSS styles; and removing the markup and CSS was a pain.
If the plugin had an easy way to disable default output and allowed me to use some built in functions to get just the post IDs or post objects for related posts, then I would’ve been golden.
Next time you’re writing code, or if you can adapt your plugin still, remember to GoomWay. I and many other folks that want to use your wonderful plugin will thank you.
