When it comes to writing code specifically for WordPress, I try my best to follow a combination of the WordPress coding standards, tips and advice from various books I’ve read (which I hope to cover in a future post), tips from others in the community, and certain habits that I’ve developed along way the way.
The thing that I’ve always struggled with determining is what constitutes clean code. There is code that follows standards, then there’s clean code, and I think that the definition is almost somewhat subjective.
With the open source nature of WordPress, the desire to improve education around the platform, the desire to improve the plugins repository, and the existence of things such as Theme Review team, Theme Unit Test, and tools specifically for helping us write code, there’s an innate desire for programmers to write clean code – I just think that we could do a better job defining it.
To be clear, I don’t believe that clean code is synonymous with quality code, nor do I believe that clean code is synonymous with good code. They’re absolutely all related, but they aren’t the same thing.
With said, what does constitute clean code specifically in the context of WordPress development?
1. It Follows Standards
I want to be clear that I do not think that writing clean code in the context of WordPress constitutes breaking away from the standards. In fact, I think that for any framework or library – be it .NET, Rails, jQuery, etc. – that you play by the rules first, write clean code second.
So I think that the first pre-requisite for writing clean code in WordPress is that you have to follow the standards. We all need a foundation off of which to build and standards provide just that.
The problem is that I think we often view standards like laws – they’re there, but we still, say, speed, right? If we can’t follow the rules, then is it really possible to write clean code in the context in which you’re working?
I think you could make a case for it, but only if the standards are weak. That isn’t something that can be said about WordPress.
Start with the standards and move up.
2. English Readability
If it was something that everyone could do (or wanted to do), then it wouldn’t be called code, right? The funny thing about writing code is that the longer than you do it, the more difficult it becomes to “unsee” it.
It’s like reading or riding a bicycle: Once you’ve done it, it’s hard to remember what it’s like to not do it.
To that end, I don’t believe that code is ever going to get to a point where it reads with a natural flow. There are technical reasons for this, but I digress. This doesn’t mean that we can’t make an effort to improve it, right?
Take a look at the native WordPress function in this conditional:
if( is_user_logged_in() ) { // Do work for users who are logged in } else { // Do work for everyone else } // end if/else
If you read that aloud, it literally reads like English (or whatever your native language is – I’m not here to discriminate :). “If the user is logged in, then … otherwise, …” That’s the type of stuff I believe that we should aim for.
Here’s an example from a project on which I’ve been working:
function gm_get_total_goals_for( $user_id ) { $query = new WP_Query( array( 'post_type' => 'goal', 'author' => $user_id ) ); echo $query->found_posts; } // end gm_get_total_goals_for
Now when this particular function is called, the line of code may read like this:
gm_get_total_goals_for( wp_get_current_user()->ID );
I think the function could be improved by even taking in the user’s name rather than the ID, but you get the point.
When you read the function aloud, it has a more natural flow to it.
3. Function Size
In Clean Code, Bob Martin says the following:
The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that. Functions should not be 100 lines long. Functions should hardly ever be 20 lines long.
This is one of those suggestions that I love, but have a hard time implementing usually because it requires a significant bit of refactoring.
For me, this is what happens:
- Write a function definition and write comments out for what the code should do
- For each comment, write the code necessary to make it happen (testing along the way)
- Move on to the next task
But for each single line of code, you could be looking at 5 – 15 lines of code, right? Those should be single functions which would ultimately contribute back to the whole point of readability.
Rather than “Move on to the next task,” I should be taking time to refactor and improve the code. This will help not only myself, but future developers.
To be clear, I’m getting better at doing this – but I’m not yet where I want to be. It’s what I’m aiming for.
Rather than writing functions that consist of multiple blocks of code, have each function represent a block of code.
But that’s not all…
There are so many things that can contribute to writing clean code that I can’t outline them all here. Besides, if it’s a truly subjective matter than that means that are probably going to be things on which we agree and on which we disagree.
But I’m hoping for this to be more of a discussion than some op-ed on my personal attitude about the topic. I’ve shared three thoughts of my own, but I’m genuinely interested in what you guys have to say.
So, for you, what constitues clean code in WordPress?
Leave a Reply
You must be logged in to post a comment.