On this site, we spend a lot of time sharing information and discussing how to accomplish certain things with WordPress. After all, the purpose of the site is to provide tutorials - that is, we attempt to give practical advice on how to build certain things using the platform.
But development isn't strictly about writing code and building things. It's also about writing quality, maintainable code, refactoring and improving the state of our projects, and generally trying to leave a codebase in a better state than it was when we found it (or when we began creating it).
So rather than focus on how to build something or review any particular code, let's review a few practical tips for writing quality WordPress code.
WordPress Coding Standards
First and foremost - and although we discuss this a lot - it's worth repeating over and over:
Following the WordPress Coding Standards is one of the most significant things that you can do when writing your themes, plugins, or applications.
For those who are unfamiliar, the WordPress Coding Standards provide rules for how we should be formatting our WordPress-based PHP. Of course, there's nothing to actually enforce the rules - you can ignore them (and many do), but it's considered a best practice for those who are serious about developing WordPress-based projects, and it's respected by those who are active in the community.
Furthermore, following coding standards means that we - along with all other developers who also do it - will have similar looking code. In fact, one of the goals of defined coding standards is so that the code looks like it has been written by a single developer.
Another advantage to doing this is that it also makes it easy for others to contribute to our codebase. After all, since WordPress and its derivative works are open source, others may want to come along and fork or contribute ultimately giving them the ability to easily read our code.
Lastly, this isn't necessarily a call to action to go back and refactor everything you've every done. Now's as good a time as any to begin following the standards. Good developers are improving all the time, so it's totally acceptable to start now (even if it's in the middle of a project).
One of the most helpful things that you can do when writing code is to leave helpful comments that explain exactly what it is you're attempting to do.
Sure, writing comments takes a little bit of extra time, but remember that if it were easy to read, it wouldn't be called code.
Think about it this way: Programmers are notorious for going back to their previous projects and recognizing how bad their code is, or how we would do something different if we were working on that project now.
If we say that about our own code, what must others think when they see our code especially if they're coming from a more experienced background?
For more in-depth thoughts on commenting both server-side and client-side code, be sure to review this series.
Another thing that we developers can do is to simplify our functions. Though I realize that this is somewhat of a subjective area, I think that aiming for smaller, more focused functions makes the code more readable and can ultimately help with testability (if you're interested in going that route).
First, it's not at all uncommon to see functions that exceed 30, 40, or 50 lines. The problem is that these functions are often doing more than one thing.
This is problematic because:
- It can make diagnosing the problem more difficult to trace when a bug arises
- It can decrease the readability of the code by making it more difficult to give the function a unique, descriptive name
- It can make it difficult to write specific unit tests because the functions aren't doing specific things.
So, with that said, there are some practical tips that we can follow to improve the quality of our functions.
If you find yourself writing the same thing over and over among different functions, then that's a case for when you need to extract that particular part of the code and move it to its own function so that it can be called by all of the places that it currently exists.
If you find your code being either complicated to describe with comments or difficult to trace while reading through it then it may be worth taking a step back and refactoring your code into something a bit simpler.
This looks different in each situation, but striving for readability over complexity is often times a better goal to strive for rather than simply getting something working.
Get in Line
This is arguably the most subjective point, I think it's worth bringing up and that's simply that we should strive to keep our functions small with 20 lines long being a relatively solid length for which to aim. Sure, this can be somewhat of a challenge with the way that WordPress often requires us to create large arrays to pass as arguments, but you get the idea: keep them small, focused, and maintainable.
Yes, this will result in more functions, but the code will be easier to read and maintain as each function has a single specific purpose. This means you can name them with greater clarity and provide unit tests around them more easily.
Obviously, none of the above are hard rules that have to be followed - they're simply suggestions for how to improve the quality of the code that we write, that we maintain, and that we contribute to others' work.
Above else, I believe that we should be striving for readability and testability. Keeping those two goals are the forefront of our work will help drive everything else into its proper place.
Of course, this isn't a complete list - it's far from it! So please offer up your suggestions in the comments!