I’d like to think that one of the things that most good developers continually strive for is writing the cleanest, most maintainable code possible.

Personally, I don’t know if there is an actual point at which you reach it – it’s the whole journey-not-a-destination thing – but that doesn’t mean that we shouldn’t continually aim to get better at what we do. In our case, that’s writing clean WordPress code.

The thing is, there’s only so far you can get on your own. You can read a number of books, follow the advice of some high profile programmers, and read as much of the “academic” material that you can get your hands on – and I think all of the above is great – but, at the same time, it only goes so far.

To that end, I think it’s worth seeking out other people in your same field to help provide some level of mentorship on how it relates to writing clean code because here’s the thing:

As much material as we can read written by other people, nothing beats interacting with those who are writing code in the same language(s) for the same APIs under the same coding standards and who are farther along than you in experience.

Two Tips for Clean WordPress Code

To be absolutely clear, I think it’s a great thing to read and follow those who advocate for writing clean code even if it’s not within the same language or toolset in which you’re working. Although many of the examples may be designated to, say, some other language or some other type of program, the principles can still apply.

At the same time, finding those who are a little further than you in experience within the same field and talking with them can help yield quicker results as it can help shortcut your learning through bypassing their mistakes and things they’ve learned.

All common sense, right?

Lately, one of the things that I’ve been working to do is to work to try to write clean WordPress code (or cleaner WordPress code, if that doesn’t come off the wrong way).

To that end, I’ve been browsing code of a number of other notable developers (thanks GitHub!) but have also sought out the advice of other prominent developers such as Gary Jones to pick their brains on how they do things, why they do it that way, and then have a conversation as to why that’s a better way.

With that said, here are two quick things that I’ve been working to implement in my code that I’ve not always done.

1. Filter, Documentation, Function

If you go through some of my previous posts or previous code that I’ve shared, then you’ve likely seen that a lot of my code has the following format:

  1. Documentation
  2. Function
  3. Filter

Specifically, it looks something like this:

But there is room to improve this. A more readable order is:

  1. Filters
  2. Documentation
  3. Function

Or, more specifically, something like this:

This allows those who are reading your code to know which hook is being used, the documentation for the function that gives a clear explanation as to what’s going on (as well as what a PHP docblock parser can read), and then the actual function definition.

It’s a much more natural flow, right?

2. Refined Documentation

One of the things that I’ve always struggled with is how much documentation and/or code comments to provide. That is to say that when it comes to the function definition, I’m fine with providing a smaller set of documentation if the actual function body as liberal comments.

That’s backwards.

To be clear, this is problematic not only because parsers won’t be generating detailed documentation about your API, but because it’s also in contrast to what the WordPress Coding Standards define.

WordPress PHP Documentation Standards

Documentation has a strict format that I think should be followed not only for the parsers that are available, but to leave as little guess work up for other contributors and programmers to have when working with your code.

Then, as far as comments are concerned within the function body, if you’re aiming to keep your functions relatively small (part of the SOLID principles), you may be able to cut back on some of them.

After all, each function will be clearly defined in their docblock, the function will be relatively short, and will be defining the coding standards for the particular environment in which you’re working.

What Are You Doing to Write Clean WordPress Code?

Naturally, there’s much more that I could cover here, but we only have so much time to read and I don’t want to write a post that covers every aspect of the improvements that I’m trying to make.

There’s more time and other posts for that, isn’t there?

What are you doing?

What are you doing to write clean code?

But the above two points are some are two of the most significant things I’ve been working to improve for my sake, for contributors sake, and at the advice of other, more experienced programmers.

With that said, I’m curious as to what you’ve been doing to write clean WordPress code, or what questions, comments, and advice you have about it.

Category:
Articles
Tags:

Join the conversation! 20 Comments

  1. Hi Tom, great article :)

    I know some people will not be with me on this one, but I use rulers at 80 characters for documentation and at 100 for code. Not for the screen resolution thing, but as a readability improvement. I think that, with very large lines, the attention span of the reader tends to decrease, resulting in difficulties to remember what they were reading first (in fact, there are some studies about this), so this can be addressed also as an accesibility issue. I keep code up to 100 lines because with 80 I would have to break the line too often with some and medium/large statements, and that could look pretty weird. But I also find line breaking and proper alignment easier to read for large statements that need to perform multiple checks.

    It’s the first time I comment here, but I’ve been following this blog for a while. Thanks for all your tips and recommendations, they’re all really useful (even the ones that I do not agree with)!

    • I know some people will not be with me on this one, but I use rulers at 80 characters for documentation and at 100 for code. Not for the screen resolution thing, but as a readability improvement.

      I used to do the same thing (for almost 10 years, even) but recently relaxed my constraints a bit.

      Thanks for the link you’ve shared, too – love reading stuff like that.

      Thanks for all your tips and recommendations, they’re all really useful (even the ones that I do not agree with)!

      Of course! And thanks for the kind comment. Love hearing from people who read – even those who don’t always agree :D.

  2. I currently take my cues for clean code mainly from the Easy Digital Downloads plugin and Jetpack.

    I do like the way Pippin Williamson writes his plugins. Especially putting the includes in a function and hooks in another function etc. and then calling appropriate the functions to set up the hooks and filters.

    I was originally putting the call the these functions in the constructor of a main plugin class. But recently I have moved them to a ‘run’ method because I felt that the constructor should do as little as possible and not give the developer creating the class any nasty surprises.

    I notice in your example that the code is not in a class? I have seen that in themes classes do not seem to be used as much as in plugins.

    • EDD is a fantastic place to review code — Pippin is a great programming.

      As far as where to place the hooks, I also like the idea of separating concerns a bit so that we have a manager for hook definitions and then classes dedicated to implementing the actual hooks.

      I’m going to be doing this with the next version of the Plugin Boilerplate, too.

      I notice in your example that the code is not in a class? I have seen that in themes classes do not seem to be used as much as in plugins.

      Exactly. Themes are mostly procedural.

  3. Hi Tom,
    I recently spent a good amount of time rewriting Top 10 just to make the code more readable and better conform to WordPress’ standards.
    The next step is to cleanup the code on my other plugins to just make them look better!

  4. Thanks so much for this, Tom (and for your many other posts about WordPress coding standards). I’ve been learning and writing a lot more functions lately, and my logical, linear brain kept wanting to do Documentation, Function, Filters but I kept seeing the Filters, Documentation, Function method lots of places with no explanation as to why. Can’t tell you how much I appreciate the clarification!

    • Documentation, Function method lots of places with no explanation as to why. Can’t tell you how much I appreciate the clarification!

      Sure thing, Nichole! But I’ve gotta give credit to Gary for planting the seed in my head for considering it myself :).

  5. I personally try to follow the WordPress Theme Boilerplate and other themes written by you, Tom. I also rely heavily on my IDE, PHPStorm, to handle these things for me as well.

  6. Great high-level tips. I particularly struggle with clean code in theme files that mix PHP and HTML. Also, no matter how much I change/improve, I am sure I will come back in 6 months and wonder what on earth I was thinking =D

    Coding is an art that can always be improved upon. Taking the time to recognize the importance of clean code and working to improve it is definitely a sign of a developer that cares. Furthermore, a developer that I would want to hire/work with.

    • I am sure I will come back in 6 months and wonder what on earth I was thinking =D

      Yep – it’s just the nature of what we do, I think :).

      Taking the time to recognize the importance of clean code and working to improve it is definitely a sign of a developer that cares. Furthermore, a developer that I would want to hire/work with.

      Agreed on both points.

  7. One thing I definitely don’t do is follow the WordPress code styling guidelines. All the extra spaces between brackets and braces makes no sense. Luckily, if you are ever involved in a project that requires strict WP code styling, you can use an IDE like PhpStorm to just refactor all the code based on that standard.

    • One thing I definitely don’t do is follow the WordPress code styling guidelines.

      I wrote a post about this not too longer ago. In short, I see it as that if you’re participating in writing code for an application or framework that has a defined set of coding standards, then it’s best to play by the rules of the sandbox in which you’re playing.

      On top of that, the entire goal of having coding standards is so that code that’s written for core or for things written on top of core should ideally look like it’s written by a single developer – and this is true not just for WordPress, but Ruby, PHP, .NET and so on.

      I used to not be a fan of all the white space, but the more I’ve worked with it, the more I’ve begun to appreciate it because I think it makes the code much more readable.

      But, with that said, you’ve piqued my curiosity as to why it makes no sense but the absence of space makes more sense? :)

      Anyway, regarding your comment on the IDE, you’re absolutely right. There are always ways to help enforce the coding standards.

  8. Nice article, I’m not a fan of the “filters at the top” approach though not sure why it doesn’t seem so natural to me.

    • Yes Javier, I am also feeling the same. Documentation at the top is what I feel right, for me atleast. :)

    • For me personally, it doesn’t seem nature because of habits from other languages, but when I consider it purely from the perspective of trying to make things as close to English at possible, it seems to flow:

      “Here’s the filter that I’m about to read, here’s details about it, and here’s the implementation of it.”

      Of course, different strokes for different folks :). Obviously I’m a fan.

  9. I do the same thing and study developer’s code that I think are keeping the standards the highest. Fortunately, there’s a lot of them around and they aren’t too hard to pick out. After a while, I think we all have our favorites for one reason or another.
    In addition, I try to read the philosophies of those people and find interviews, podcasts, articles, and other resources where they talk about writing high-quality code.

    Two books I can recommend for this topic that I’m currently reading are: ‘New Perspectives on Web Design’ by Smashing Press (Smashing Book #4) and ‘JavaScript: The Good Parts’ by the illustrious Douglas Crockford. ‘New Perspectives’ is a series of chapters by a ton of highly respected developers from around the world and, although the title says ‘web design,’ it’s far more about the whys, hows and what -fors of writing clean, scalable, future-resistant code, and not so much about “design” as commonly perceived.

    • Crockford’s book is a must read, in my opinion.

      In fact, I’d go as far as saying that’s is a must read and then a keep-around-for-reference. When I read that a few years ago, it changed the way I wrote (and understood) JavaScript.

      Definitely one of the books I’ve read on the topic.

      Okay, done gushing now.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.