Half-Elf on Tech

Thoughts From a Professional Lesbian

Category: How It Is

Making philosophy about the why behind technical things.

  • Names, Short Names, and More Names

    Names, Short Names, and More Names

    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: [plugin-name data="type"]

    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.

    They do. [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.

  • A Day Without Me

    A Day Without Me

    For the first time in over three years, there will not be a post about tech or tech adjacent items today.

    Today, March 8, 2017, is International Women’s Day. And today I do no work.

    Read more about A Day Without a Woman.

  • A Day Without Women

    A Day Without Women

    I am writing to inform you that I will not be working on March 8th.

    The Women’s March organized this day in the same spirit of love and liberation that inspired the march on January 21, 2017. Today, A Day Without A Woman, is a recognition of the value that women of all backgrounds add to our socio-economic system. It is to raise awareness and remind us all of the pervasive and systemic gender-based inequalities that still exist within our society, from the wage gap, to vulnerability to discrimination, sexual harassment, and job insecurity.

    I am one woman. On any given weekday, I read a thousand lines of code. I review between 30 and 60 plugins. I write at least 2,000 words on WordPress.

    But not March 8th.

    On that day, I will review no plugins.

    On that day, I will answer no questions in the forums.

    On that day, I will not work on WordPress.

    I’m one person, and I do shy away from the political on this blog, but now, this year, this time is different.

    I understand if you can’t, we can’t all afford to do this, we can’t all risk this. But I can. And I will. Because I am one person, but my family taught me to care about everyone, not just myself. I am one person, but together we are a nation. I am one person, but I am not alone.

    So on March 8th, there will be no WordPress for me.

    I hope you will stand in support of me, and any of my friends and colleagues. I hope that everyone will give women workers today off without retribution. I hope you will all stand with me and others.

    I know this is a big ask, and I know a lot of you can’t. I understand that, I respect that, and I support that. We need to eat.

    I am dedicated to my work. I am dedicated to WordPress and DreamHost. I respect them, the work we do, and their values. And I am grateful my company does support me when I chose to do these things. I am lucky and thankful and grateful I won’t be fired for taking this day off.

    At an increasingly insecure time for the rights of women and other minority groups, it is important to me that I also stand for the value of equality.

    I hope you, the people who read this, will support me in my decision. I hope you will join me if you can.

  • REST API – Democratizing Reading

    REST API – Democratizing Reading

    Democratize Publishing.

    We say that a lot in WordPress. We boldly state that the goal of WordPress is to democratize publishing through Open Source, GPL software.

    I’d like to turn that on it’s ear for a moment.

    The purpose of the REST API is to democratize reading.

    Democratize Discovery

    One of the myths of websites is that if you build it, people will come. If that was true, we’d never need plugins like Yoast SEO and we’d never need to self-promote. The reality is that we have to work hard and make our content good. WordPress helps us make it look good, and makes it easier to get it out there, and usually the rest is up to us.

    There’s another aspect to discovery, though, and that is the ease of findability. We already address this in WordPress to a degree with RSS, but as much as I’d love to say that was that, it’s not. It’s 2017. People don’t want RSS, they want email and they want the information on social media immediately.

    And? They want apps on their phones that alert them to new data.

    Democratize Consuming

    Reading data with WordPress is easy. We go to a webpage, we see the data, we consume, we move on. With emails and social media, people usually have to click to come to your site and read. While this is good for your traffic, anytime a person has to click you’re running a risk they might not click. That’s why Tweetstorms are more consumable than blog posts. While they are far more transient, they’re accessible in an immediate way.

    Making the consuming of data more direct, a more one-to-one relationship, improves the chances that someone will actually read the information. Much of this can be achieved with a good lede, but readers are well to aware of click-bait today. “She tried this blogging software. You won’t believe what happened next!”

    Right. You get the point. In order to get people to read, you have to make it easier for them to read. Converting WordPress posts to something an app can read needs to be easier for the blogger, or they won’t be able to have success.

    Democratize Reading

    The REST API does just that.

    It makes the discovery and consumption of your website easier by simplifying your output.

    When you look at a website you see the design and the layout and the wonderful beauty. When an app reads your data, however, it doesn’t want or need any of that. An app needs the raw data. And the REST API does that. It outputs the data in a super basic and simple way. Furthermore, it lets you add on to this and output specific data in special ways.

    Democratize Publishing

    You can publish your data in multiple ways. Today, we all know about the blogging aspect of WordPress. But here are some other ways you could share your data:

    • Allow users to download a CSV with all the products on your site and their costs
    • Create a plugin that calls custom data, allowing others to have a widget with the data
    • Power a mobile app without loading your theme

    Could you do all that without the REST API? Of course.

    Does the REST API make it easier and thus help you democratize faster? Yes. It does.

    The REST API can change your life, if you’d only let it.

  • A Case for REST API

    A Case for REST API

    WordPress 4.7.1 and 4.7 were vulnerable via the REST API. Any unauthenticated user could modify the content of any post or page on a site. Since the release of the information, a surprisingly large number of users failed to update to 4.7.2 and, thus, were hacked.

    I say surprisingly because WordPress enabled automatic updates quite a while ago (WordPress 3.7), which will automatically secure your WordPress install. There have been 18 automated releases since then (which is why we have 3.7.18) and the vast majority have addressed security in one way, shape, or form.

    But this post isn’t about the reasons why someone might need to disable the automatic updates. No, this is about the argument I saw stem from the vulnerability, whereby people said it was proof the REST API should be disabled by default.

    And to them I say “No.”

    The REST API Probably Has More Vulnerabilities

    Look, I’m not going to lie to you. The odds are high that the REST API, which is a very new feature, probably has some serious issues still. But, as my friend Helen pointed out to those arguing for it to be disabled by default.

    Why should this be treated differently from XML-RPC? Have you gone through the history of the XML-RPC setting?

    While the REST API may introduce new vulnerabilities to WordPress, and even ones that are horrifyingly accessible to non-logged in users, it is not the first nor the last feature WordPress has added that puts a site at risk. The API, being brand new and not used or tested as much as other aspects of WordPress, is going to be dangerous to exist, but realistically not more or less than any other part of WordPress.

    Go through the list of all WordPress security releases. A lot of issues have been fixed. This is just the first one for the REST API.

    In 2008, XML-RPX in pre-2.3.3 systems allowed remote attackers to edit posts of other blog users, if registration was enabled. That’s a long time ago, and since then the majority of the exploits have revolved around DDoS and pingbacks. But yes, back in the day, this new feature was also problematic.

    Do You Trust WordPress?

    Everyone makes mistakes. Every code has bugs. Everything is vulnerable. The question you have to ask is not “Why did WordPress let this happen?” nor “Why did they put me in danger?” but “Did they handle this well?”

    The heart of the matter is not if you trust WordPress not to screw up, but that you trust them to react responsibly, quickly, and with the appropriate concern. Some security issues are massive. Others are not. With over 26% of the internet using WordPress, fixing the security issues quickly and properly is a huge concern.

    So you have to ask “Do I trust WordPress to fix security issues?” And “Do I trust WordPress has my best interests, with regards to security, at heart?”

    I do, but it’s a question of risk.

    Risk = {si, λi, xi}

    My father, a risk analyst, asks three important questions:

    • What can go wrong?
    • How likely is it?
    • What are the consequences?

    Obviously a lot can go wrong. So much, in fact, that it can be impossible to wrap your head around the vastness of the possibilities and subsequent probabilities. Even just listing the things you think might go wrong is incomplete. You know you’re not thinking of everything, so you have to start with the big picture.

    Most of us aren’t capable of calculating the risk and reliability of WordPress. Those Six Sigma experts aren’t either. There’s no way I could actually explain well enough how to determine the risk of using WordPress. If I could, I’d start with asking people “What can go wrong if I disable automatic updates?” and “What can go wrong if I don’t disable automatic updates?”

    The likelihood of the REST API being vulnerable is a little higher than other aspects of WordPress core, but much lower than plugins and themes. The consequences are generally higher than that of plugins and themes, but there’s an extra factor you must consider.

    • How quickly can it be fixed?

    If you leave WordPress auto-updates on, then the answer is “As quickly as humanly possible.” And that, I feel, lowers the overall risk.

    Planned Disclosure

    To those arguing WordPress should have told everyone sooner, this is not the first time WordPress waited a while before announcing a security issue. Take, for example, The Case of the Trojan Emoji. That’s not a Sherlock Holmes mystery, that’s the true case of where WordPress hid a major security fix inside the additions of emoji support.

    There’s a big difference between the Trojan Emoji in 4.2 and the RESTless Backdoor we faced in 4.7, and that is the exploitability. The vulnerability fixed with emojis was hard to do. The one in the API was super easy. In both cases, however, the moment the vulnerability is disclosed, a ticking clock begins to see when people get hacked.

    Sometimes folks tell me I’m hyperbolic or exaggerating when I say ‘attacks will begin within minutes.’ I think that my claim was proven valid, considering how many sites were hacked, and how quickly it happened. Within days of the announcement,

    Remember, security is nuanced. It’s never as simple as “Hey, I found a vulnerability! Patch it!” It requires testing, validation, more testing, and more testing. A good patch doesn’t introduce worse problems (yes, that’s happened before).

    Rarely Used Code Is More Vulnerable

    I bring this guy up every time people argue why WordPress turns on features by default. The WordPress argument is that if they don’t turn it on, people won’t use it. The reason that matters can be found in the works of Herbert Hecht.

    Hecht wrote papers about rare conditions and their effect on software failures. The tl;dr summary for you is this: Rarely used code fails more often.

    Now, Hecht specially was referring to the early days of software use, which the REST API certainly falls under, but the basic philosophy is valid. The less the code is use, the more at risk it is, specifically because it’s used so rarely. People are less familiar with it, they don’t know how to fix it or even test it for all the possibilities, because they don’t yet know what they are.

    Are those reasons to not use the REST API? Not always. You have to consider the risk of using it for yourself. Will your site go down? How bad is that if it happens? Are you doing everything you could to protect yourself?

    Should You Disable The REST API?

    No. Unless you’re certain you’ll never use it, ever, leave it on. It will be fixed, and as long as you apply security patches promptly, you’ll be fine.

  • Prefix or Suffix

    Prefix or Suffix

    I’ve been seeing a lot of a new trend in coding, which stems from boilerplate plugin code, and that is the use of suffixes in function names. This has become increasingly popular in WordPress code and I, for one, am not a fan.

    WordPress Function, What’s Your Function?

    Otto likes to say that well named functions don’t need code comments.

    While optimistic in this day and age of complex code, the basic concept remains quite valid. If you name your functions well, the chances are that they will trigger your contextual memory and you’ll remember what they are, what they do, and why they’re there. To this end, the difference between function activate_pluginname() and function pluginname_activate() is miniscule. Both of those are clearly functions that run on ‘activate’ and that makes perfect sense. We can see the purpose of the function by its name, and that is the majority of Otto’s point. They are well named as they indicate their job. The issue then does not like in the name of the function but in the format of the name of the function.

    Function Name Conflicts

    A majority of the time, my argument for having unique function names is that there are over fifty-thousand plugins out there, and the odds of two of them having the same function name is quite high, for cases when the function name is generic. For example, function my_plugin_init() is not unique in the slightest. Yes, people literally use my_plugin_ as a prefix. That’s not a placeholder. That particular error occurs when people use boilerplates and don’t read the directions clearly. Most state “Search and replace my_plugin with your plugin prefix.”

    Preventing conflicts means it’s incumbent of developers to select unique function names. Now this pressure is alleviated by the use of namespaces and classes, but even those have to be unique to their plugin (or theme). After all, class WordPress is not a great classname.

    Again, in this regard there is very little difference between function activate_pluginname() and function pluginname_activate() in the real world. Both are unlikely to cause conflicts.

    Internal Consistency is Good

    Another aspect of names is that good function names are logical and consistent. Few things pain me more than seeing function pluginname_init() and function pn_admin_init() (where pn is an abbreviation for the plugin name). What I see a great deal with the plugin name as suffix is this hodgepodge of names:

    • init_plugin_name()
    • plugin_name_uninstall()
    • pn_wp_class_list()

    My guess at this point is that any time a particular boilerplate doesn’t specify the name of the function needed, people fall back into old habits. Or rather, they fall back into the recommended habits. You know, a prefix. Consistently named functions make it easier for people to recognize what function belongs to what plugin or theme.

    So why Prefix?

    This takes us to an interesting point. Both function activate_pluginname() and function pluginname_activate() meet the requirement of being well named and unique (and can be consistent). So what actually is the problem here?

    The problem is the future.

    Your code does not exist in a vacuum! Code that will only ever be used on your own server still runs with the other plugins and themes you add, and they could cause a conflict. It’s somewhat trivial to change those things, but it’s not fun and usually it means that you broke something in your live environment.

    • Consistently named functions make it easier to know what function relates to what.
    • Uniquely named functions are easier to find.
    • Well named functions remind you what the function is supposed to do.

    But again, why prefix?

    Remember Who Comes Next

    I do a lot of searches on code in myriad plugins. More than most people involved in WordPress I suspect. I have a very peculiar relationship with plugins, after all. When the core developers want to figure out how ‘well used’ a function is before changing it, I help out by running a search on all the code in the plugin directory. This results in me finding a lot of weirdly named functions that require me to track back through the plugin and find out what it’s really doing. When things are prefixed, this search goes a lot faster.

    Besides just my convenience, when you remember that your code is used by thousands of people, they will have an easier time searching for your code when they have an error. If you got an error that a function named halfelf_init was doing something wrong, you could run this to find the file: grep -r "halfelf_init" ./wp-content/

    Some of the more experienced debuggers out there are probably wondering why I grep from wp-content when most errors give the full path of wp-content/plugins/plugin-name/filename.php in the first place. The answer to that is “most” but also because often functionality plugins that are related to a theme (or other plugins) will cross-reference themselves in ways that can cause PHP to give you the wrong file for the problem.

    If you ran my check and found that the function was called in nothing but files in that plugin’s folder, great. But if you found it was called in a theme, you would then want to run this: grep -r "halfelf_" ./wp-content/themes/theme-name/ — That would reveal all the calls for the functions that belonged to a specific other tool.

    And what if you got a warning that the function had already be declared? grep -r "function halfelf_" ./wp-content/plugins/other-plugin/ will list all the functions that start with halfelf_ and save you a headache of solving one warning only to have it be replaced by another. (Of course, if you use namespaces or classes, this gets thrown out the window, oh well).

    Finally there’s the human factor. This is exceptionally subjective, I know, but doesn’t a line of functions all starting with the same term feel cleaner to you? It demonstrates a repeating pattern that a human mind can follow and feel comfortable with.

    Solution: Be Consistent

    There’s only one solution to be had here. While I greatly prefer a prefix, if you chose to use a suffix, be consistent. Make every single function end with _pluginname and don’t skip a single one.