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:
Specifically, it looks something like this:
But there is room to improve this. A more readable order is:
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.
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.
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?
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.