Writing WordPress Code – Clean, But Not Clever

I think of one the biggest challenges that programmers face as we become more comfortable and well-versed in our programming language(s) of choice, is that we become intimately aware of some of the more clever things we can do with the code.

For example, one feature of dynamic programming languages is that they offer anonymous functions. They’re really powerful and you can do some really cool stuff with them, especially in JavaScript; however, this always introduces a tension:

Are we writing code to be clever or are we writing code for others to understand?

Since I spend the majority of my time working with and writing about WordPress, I thought I’d share my thoughts on writing WordPress code.

Hey, It Works … It’s Alive!

It's Alive!

When I first start writing code – and not just WordPress-specific code – but when I was really learning to write code, I felt good when I just got something working.

I didn’t care how long many lines of code it took nor did I care if I was following any sort of best practices.

I think this is relatively normal for any budding programmer. At least, I hope it is. Anyway, although getting something working is always exciting, this should never be where we stop writing code.

This is no less true when writing WordPress code. I still use the Codex daily – specifically, I still look to make sure there’s not an API function already available for something I’m about to attempt.

Get it working, then work on writing better code.

Oh, But Think of the Clock Cycles!

Think of the Clock Cycles

After I became more comfortable writing code, learning my way around the IDE, understanding how programming languages work, how processors work, etc, etc, etc., I began to try to optimize the heck out of everything. Literally, I would think

…and how many cycles will this take?

Give me a break.

At this point, especially for those of us who are writing WordPress code, we’re dealing with a web application.

  • Think about the machines on which our work is running. Multi-core processors, more RAM than we could ever need, and virtually endless hard disk space.
  • Remember, there is middleware WordPress and the machine – PHP. We need to do our job writing solid PHP code and let the PHP interpreter do its thing; otherwise, we could cause it to do more work than necessary.

Now this is not an excuse to be lazy or irresponsible – clearly, I care about performance – but I to make sure that we’re optimizing the right things. Clock cycles? Not so much.

Besides, the API is there for a reason. Saying that you can do it better than whatever the API offers is a bit arrogant, especially when you’re one person working with an API that thousands of people have contributed to developing.

I’m not saying it isn’t possible, but it’s highly unlikely.

The Story So Far

Cool Story Bro

At this point, I think I’ve struck a pretty good balance between writing clear, maintainable code that’s considered optimal. Granted, one can only speak in terms of where he currently sits, but I know that I’m doing a better job than I was several years ago (let alone last year).

When it comes to writing WordPress code, I think there are three key things to do:

  • Learn and follow the WordPress Coding Standards (especially the part on clever code)
  • Write code, a lot of it, and don’t stop when your project just works. Have it code reviewed!
  • Spend some time with the PHP manual learning the features of the language

The truth is, it’s absolutely possible to build products with WordPress without truly learning PHP just as it’s completely possible to write client-side applications using jQuery without truly learning JavaScript.

I’m not advocating that you learn the foundational language first, but learn it as you go. I think that will make for a better programmer.

And Finally…

At the risk of sounding cliche, it comes down to just because you can, doesn’t mean you should. And sure, developers always will, but at this point, I’m much more concerned with writing code that I can maintain for years, or to which others can contribute rather than writing some comes off as difficult to understand.

It wouldn’t be called code if it was inherently easy to understand, right?

Finally, I believe that this is why we have such a mish-mash of quality when it comes to WordPress themes, WordPress plugins, and other WordPress-based poducts:

We have developers who care more about getting something working and shipping it rather than taking the time to improve the quality of what powers the product.

For shame.

Spend time building your product and make improvements over time – you’ll have no choice but to become a better at writing WordPress code.

11 Replies to “Writing WordPress Code – Clean, But Not Clever”

  1. Nice post, Tom. I feel this is (always important, but) especially important when you’re part of a team, or working on a client site where other developers are bound to come along behind you. It may be slightly more efficient to do something the clever way, but it sure can make it tough for the next person to figure out what you did.

    One thing I’m often guilty of that I wouldn’t put in this bit though, is repeating ourselves in code. Sometimes (especially when I’m in a rush) I tend to write some code in whatever file I’m in, then moan when I need it again, and copy it over… Oops! I should be putting that stuff into a function and storing it somewhere safe, instead, so my code isn’t repeated in multiple places in a project. That’s tidyness, not cleverness : )

    I also like the example of clever code in the codex, but I go a little further even. To me, it’s just easier to read when curly brackets are used on as many if / elseif statements as possible. Even your average WP_Query can be a little more legible w/ brackets, imo.

    1. During my time at my previous employer, they ingrained in us “do not copy and paste code.”

      Sure, it takes time to refactor the code so that you have better organization (classes, abstracts, all of that stuff) and it isn’t always easy in the enterprise environment, but the implication of copying and pasting code is that you’re copying and pasting months (or years) worth of knowledge that probably isn’t related to the specific problem at hand.

      At the end of the day, it creates waste.

      It’s a hard habit to break, but it makes for a better application if you can really stop to notice problems like this while developing so that you can refactor during the current iteration / sprint / whatever-unit-of-work you guys use.

      Finally, I go further as well. Case in point: with curly braces, I always add them and this is for two reasons:

      1. I took a compilers class in school and writing a compiler having to parse conditional statements with implicit curly braces sucked. From that point forward, I committed to always using them.
      2. It allows me to see where when one conditional (or block) ends and another begins thanks to IDE highlighting.

      I also end each block with a comment } // end foreach or } // end if or } // end function_name_here just because I think it makes it easier to trace. All of which have come from frustrations dealing with other people’s code (include my own!).

      There’s more I could write about that particular topic alone, but I figured I’d say it for another day. I feared this particular article got too long, anyway ;).

        1. Thanks!

          Though I typically try to follow Bob Martin’s approach to keeping functions relatively succinct (that is, 20 lines or so), it’s not always possible.

          I always end my closing brackets with an ‘// end’ comment so I know which bracket it’s actually closing. I do this for class names, loops, conditionals, and occasionally for arrays if there are several nested arrays. It’s especially useful in JavaScript when you’re nested a set of anonymous functions as arguments to other functions :).

          I hope to go in more detail about this in another post.

  2. Good thoughts Tom. I agree with the tendency of devs to stop coding after something works once. It’s always important to code not just for the obvious case, but edge cases as well. In a previous life I was a tester and took great pleasure in figuring out legitimate ways to break the code developers were submitting.

    I need to remember to put on my ‘tester hat’ to test my own code so that I can ship higher quality products.

Leave a Reply