I was working on a side project with Tracy Levesque of Yikes! and she lamented at my readme. I had totally half-assed it and I knew it, so she cleaned it up and asked me “What are the shortcodes?” I told her and about a second later she suggested two new names. Hers were better.
Functionality Based Names
I have a habit to name things what they are. I made a shorcode, for example, for a number of posts in a custom post type, and I called it
[numposts] because that made sense. But when I added in a new one for number of posts in a taxonomy, I made a second shortcode named
[numtax] which is kind of silly isn’t it?
My problem is that I think about each shortcode as it’s own, stand-alone entity. It’s a functional thing. It does a thing. A function should be named uniquely to be clear what it’s for.
Usage Based Names
Perhaps without meaning to, Tracy jolted my brain into thinking about not the developer but the end user. Now, in my head, I thought “The user would know which shortcode to use and doesn’t have to think about more.” But. She suggested this:
I stared at that for a moment and felt the light slap me in the face. I’d named the shortcode for their function, but not for the plugin they were in, which is akin to all those terribly named functions and classes I’m always ranting about. In short order, the plugin was fixed and I turned back to my posts code.
One Name to Bind Them
[numposts data="posts" posttype="post-type" term="term-slug" taxonomy="taxonomy-slug"]
The code defaults to a data set of
posts and a post type of
post since those are the most common usages. After that it’s a fast check “Is this a posts data set or a taxonomy one?” and runs the same code it used to run, passing the data along.
What’s Really The Difference?
“But Mika, now people have to type in more!” I hear you say.
[numposts] defaults to posts like it always did.
[numposts posttype="page"] is four characters longer. But with the four extra characters (and really I could have left that out) comes something simpler: people only have to think of one shortcode.
If they want to count the number of posts, then they just count the number of posts and call it a day. There’s no headache of realizing they meant to get the number of posts with a specific taxonomy. It all just works with one. Remember your terms, and those didn’t change except for needing
[numposts data="taxonomy" term="wordpress"] which actually makes it more obvious what you’re doing.
I have no idea if Tracy meant for me to get this deep into this, but she also knows I spent an hour contemplating the fact that the word ‘read’ exists in multiple tenses, and it’s only by context that I actually know which one anyone meant.