As one of the most popular open source CMS in the world, WordPress really makes it easy for us to create stunning websites. However, this advantage can easily become a problem if developers of themes and plugins don’t follow certain standards when developing new products. Most of the WordPress best practices are already covered in the Codex, but I think it contains so much information that it can be difficult to understand where and how to start. To make things easier, I decided to refine these recommendations for you.

You have probably seen hundreds of WordPress tutorials, standards and guidelines covering WordPress development practices. In this article, I’m going to cover the 5 most important WordPress best practices when developing WordPress themes or WordPress plugins. The main focus will be writing better code, managing and testing it, and delivering best practices.

WordPress coding standards

This section is directly relevant for the developers of WordPress themes and plugins. When we talk about best practices of writing code, we need to jump in at the deep end and cover details like programming language specific tools for managing code. First, let’s discuss methods of delivering better coding practices

Readability – When you write any code in any programming language, always remember that you are not only one who will use that code. Your code must be clear and readable for any developer to use.

Your code must always include thorough notes, which will help you and other developers to understand and tweak it if necessary in the future. These notes will help outline details such as the code’s function, why it was coded in a certain way, who wrote it or where you got it from.

You can read about this in WordPress’s coding standards. Remember the Golden Rule: “When in doubt, space it out.”

Reliability – It’s likely that you already know how to write the code that it runs without any problem on several hosting environments. However, this is not always the case for everyone, and your code may fail for hundreds of reasons in different environments and with different users. As a result, you should always use tested WordPress APIs as much as possible. Even if you’re a professional coder, it’s impossible to test that code for millions of users and thousands of different server configurations.

To prevent naming conflict with other themes and plugins, always prefix your function names, class names, post types and taxonomy names.

Flexibility – The greatest benefit of WordPress is flexibility. If the code for your plugin or theme is properly written, you can take it and implement it into your project without causing a single issue. Unfortunately, errors can always happen, and the main cause of error is not following best practices.

It’s probable that your code will be reviewed in the future for tweaking or adding new functionality. Make sure your code is flexible enough to be edited in the future. For example, use relative URL paths whenever possible so that if your URL changes, you won’t have to edit all your codes depending on the URL used.

Reusability – If you think copying and pasting will make your code reusable, you’re unfortunately mistaken– copy-pasting code is a terrible idea when coding. Just imagine what happens when you want to make small changes to a code that you have already copied 15 times to different places and files? Always make sure you are not repeating yourself. If you discover that you are repeating yourself again and again, stop for a second and think about it. In a coding standard, instead of copying, you can create and pack such functions in a separate plugin. This will allow you to use it in other places and easily maintain it.

Managing code 

Writing code using the best practices and standards is one thing, but managing this code is a different matter entirely. It’s important to ensure that managing the code is easy and doesn’t involve repeating steps.

Version control is an option that makes the cowboy style of writing codes and managing versions of that code a thing of the past. Version control allows you to easily track all of the changes to your code, from start to finish. This allows you to restore your project to any specific day, divide your project into several branches to test new functions and add new features without affecting the main body of the code.

Git is the most popular version control system used for this. However, WordPress uses Subversion as a code management tool for themes and plugins. The main benefit of Subversion is that it allows you to work with others and manage different versions of your code. It’s also specifically optimized for WordPress’s needs.

Version control is the best problem-solving option out there, not only for working as a team but also for individuals. I think it’s the first thing you need to learn before starting to code anything. Another benefit of version control is that you can save your code to your local machine and host it online, using services like GitHub or BitBucket to host your codes in the cloud. This is also a great way to publish open source code and projects for others to use.

Testing code

Even if you are creating a premium product for free, it’s important to test your code in many different environments. In our case, when we develop a WordPress product, we have to test it in different hosting environments and with different versions of PHP as the main programming language.

One of the best tools you can use to test your code in many different environments is Vagrant.

Many developers don’t spend a lot of time testing their code. Some may not even put in much work to debug it. One basic way to test your code is to enable WP_DEBUG to be true in wp-config.php. This action will show you if your code has any warnings, notifications or critical errors. However, if you are a serious developer, you will definitely want to use one of the best IDE and debuggers, such as XDebug.

Deploying code

Put simply, every time you click “Update” for a theme or plugin, or even install a plugin or theme,you are deploying the code. This process is very important, as installing untested code might even break your project. For this reason, some hosts create a workflow of deployment for their code so as to prevent issues related to the installation of untested code. This is where the testing or staging environment comes into play. In order to keep user’s projects, this environment offers a stage copy of the site where you can install and update anything without breaking the main site. Once you make sure everything is working properly, you will be able to implement changes to the live environment. If something is not working, it happens only on staging and not on your site.

The main idea in code deployment is to have a flexible workflow that reduces the chances of breaking something. Errors or other issues can always happen, so you should have easy steps to roll back or restore the previous working environment.

There are several different paths you can take to deploy your code smoothly. You may use the version control system we talked about above or use deployment tools like Capistranorb or Ansible.

Code Comments and documentation

Comments and documentation are a developer’s best friends. Whenever you write code, think about whether that particular line is easy to understand and make sure you don’t need any comments to explain why you did what you did. But, trust me–when you come back to that line in the future you may not remember why you did what you did in the past. Even easy-to-understand code snippets can become a headache if you don’t leave comments related to them.

The issues with cowboy style coding are even more evident when your code must be reviewed by someone else, or when you work with a team. As we mentioned before, WordPress is an open source project, so your code might be reviewed by others at any point, and without proper documentation of the code, it might be very difficult for other users to understand it.

Comments are always welcome when writing code, not just in PHP but in HTML and CSS as well.

Conclusion

I hope you found this article useful! The WordPress Codex covers the WordPress best practices mentioned in this article in greater detail, so before starting to create new themes or plugins, make sure to familiarize yourself with the standards of creating user-oriented products.