The 12 Worst Mistakes Advanced WordPress Developers Make

WordPress is a very popular way to get a site up and running quickly. However, in their haste, plenty of developers end up making horrible decisions. Some mistakes, like leaving WP_DEBUG set to true may be easy to make. Others, like lumping all your JavaScript into a single file, are as common as lazy engineers. Whichever mistake you manage to make, read on to find out the the 12 most common WordPress mistakes that new and seasoned developers make. If you find yourself committing one of these mistakes, don’t despair. Each mistake is an opportunity to learn.

1. Placing WordPress Theme JavaScript Code into One Main File

Once, while doing page speed optimization for a client’s websites, I noticed they were using a premium theme that had all the libraries they were using, including the custom code, in one single file called main.js, theme.js or custom.js. This practice is bad for the following reasons:

1. The file, in time, can get really big as the theme, being actively developed, will grow in features and sometimes you will see files as large as 1 MB in size. The file will be loaded site-wide even if only 10% of the code from the file is needed in some pages. This will make pages take longer to download and slower to render, especially if it’s render blocking code within the head section of the page.
2. It makes managing the code inside the file more difficult, as you can’t use functions such as wp_dequeue_script() to unload some of the code in some pages to either improve the page speed or to prevent a conflict with other JavaScript code that could be loaded by one of the active plugins. Sure, the file can be split into multiple ones and enqueued in WordPress, but if at some later point, the website administrator performs an update of the theme’s main.js file, then the whole process has to start all over again.

2. Using Names That Are Too Common for Variables, Functions, Constants, or Classes

When developing a plugin, it’s better to use a naming convention that prevents code conflict in case there are other plugins using the same name. That’s why many developers prefix their variables and function names with something unique and related to the plugin itself. Beside eliminating code conflict, it also makes things easier to find when you have lots of plugins enabled.

There are developers, on the other hand, who prefer to use PHP namespaces to encapsulate items and solve the two problems authors of libraries and applications encounter when creating reusable code elements such as classes or functions:

1. Name collisions between the code they create, and internal PHP, or third-party, classes, functions, or constants
2. Ability to alias (or shorten) Extra_Long_Names designed to fix the first problem or improving readability of source code. This one is my favorite since I often develop themes or plugins that have a lot of code. With this, I can read and manage the code easily without having to worry much about having long unique names.

I’d recommend a good understanding of namespaces before using them as they can often be used in the wrong way.

Depending on the project that you’ll take on board, it’s likely that you’ll have to stick with the existing coding style, unless your work is mostly separate from the existing one. In case you have to extend an existing plugin or theme that already follows the PHP coding standards for WordPress, then it’s best to stick with them in order to have a consistent style so the code becomes clean and easy to read. Note that some rules are universally applied in order to improve performance, disregarding the coding style. For instance, it’s always best to use single quotes (instead of double ones) if you’re not evaluating anything in the string. Also, the code has to be indented in order to be read, especially if it has nested code (e.g., IFs within IFs, nested FOREACHs and FORs).

3. Not Leveraging Existing WordPress Core Functionality to Its True Potential

As WordPress comes with a suite of regularly updated libraries that can be just called in our plugins and themes, it’s best to just make use as much as possible of the existing core functionality. I’ve seen WordPress themes and plugins that had files in their assets directory that were already in the WordPress core files (e.g., jQuery or Color Picker). Besides the fact that the package will get bigger and take longer to load over the network, you also have to ensure that all the third-party libraries are regularly updated, which is just another thing to take care of.

Leverage what WordPress already has to offer, as the libraries are already updated by the WordPress development core team and you can have a lightweight and easier to maintain project. By regularly doing WordPress updates, you get access to more features (whether it’s a plugin, a theme, or WordPress core itself as its Dashboard is consistently improved) and make the website more secure in case vulnerabilities are found in the old code releases.

4. Not Making the Plugin or Theme Easy to Alter through Actions and Filters

Editing a WordPress plugin or theme directly is a bad idea, unless, of course, you are directly involved in the development of that package and contributing to its code. If an automatic update is performed to the plugin or the theme, then any direct changes to the package would be lost and you will have to edit the files all over again.

That’s why using actions and filters as well as creating a Child theme (that extends the parent theme) are the most effective approaches to modifying a theme since you can alter the existing functionality without editing the parent theme or the plugin itself. Moreover, if you’re offering a plugin for free download on WordPress.org and later on you’d like to create a premium extension that would depend on the parent plugin, then you should develop the free plugin in such a way that it would be easy to extend and add premium extensions to.

5. Developing with WP_DEBUG Set to false

By default, the WP_DEBUG constant is set to ‘false’ to avoid printing any PHP errors, warnings, and notices. On a live environment, this is a recommended choice as it keeps private server paths and scripts hidden from the public view, which is great for security reasons. However, during the development stage, it’s best to have it set to ‘true’ as it will notify us of any errors in our code. Even if the errors don’t directly affect the functionality, it will often force you to write better code and develop better coding habits. It happened to me. This will also ensure that the plugin or theme you develop doesn’t generate PHP errors in any WordPress installation.

While this is something most experienced developers do, it happens, especially in a rush. No matter how urgent the job is, developers should always try to maintain WordPress coding standards, with an obvious eye on PHP best practices.

6. Writing PHP Code without Considering That the Page Could Be Cached One Day

This is a common PHP mistake and, like the previous one, it’s relatively easy to avoid if you stick to the PHP coding standards.

Some developers have a habit of implementing PHP snippets into themes and plugins that are only valid if the PHP code is triggered all the time. For instance, a PHP function that responds to the HTTP User Agent with certain actions should be taken or not (e.g., enqueuing scripts that are meant only for mobile users).

If your client installs a plugin that caches the page (e.g., W3 Total Cache or WP Rocket) without triggering the conditionals in your theme or plugins, your PHP code will be rendered useless. If the intention is to make the pages responsive, then this should be done on the front-end side through media queries and JavaScript. The latter, only if it really is required. Ideally, you want to avoid using JavaScript to make your site responsive.

7. Not Tracking Changes Made in a Professional Way through a Version Control System Such as Git

Files that are custom coded, such as a child theme or a custom plugin, should ideally be under version control. Git creates a record of what was changed and allows developers to work together on the same WordPress project or revert to a previous version easily whenever something goes wrong with the website. Moreover, clients can use Git to keep track of all the work history that was done by all the developers that were hired for that particular project, especially if it was a large, long-term WordPress custom website.

Although it can be intimidating in the beginning, especially for junior developers, understanding Git will be worth the time and a Git GUI software such as SourceTree (one of my favorites) would simply be the way you interact with your Git repositories, making the whole learning curve more enjoyable. Once you understand how it works, consider checking Git Best Practices and Tips by Toptal Developers that explains in more depth a few ways of using Git.

8. Enqueuing CSS and JavaScript Files When They Are Not Needed

Having many HTTP requests would make the website slower to load, thus having a lower score in Google PageSpeed which would likely affect search ranking. It could also lead to JavaScript errors due to conflicts between plugins. For instance, there could be two plugins using a common jQuery library, which may be loaded twice and could causes issues. And really, this is the best example, since jQuery is very commonly loaded on live websites multiple times. This probably happens due to poorly written plugins or themes.

9. Using .php Files to Output CSS or JavaScript Code Instead of Static .css and .js Files

I’ve seen themes and even WordPress plugins that had files such as style.php that were used just to generate custom CSS code and print it. Things such as colors, font sizes and spacing around elements were set in the theme’s settings and then saved in the database. Then style.php is read (e.g., <link rel='stylesheet' type='text/css' href='css/style.php?ver=1' />) and generates the CSS code based on the custom settings that were updated in the dashboard.

This is really a bad practice in terms of WordPress performance. Here are the main disadvantages that come with it:

1. As the CSS file is loading within the head tag (which is normal and most of them are loading like this), there is a performance issue that comes with this as the browser has to download the file completely before rendering the page. If the WordPress environment is slow because of some plugins, then this will delay the load time considerably. Even if caching techniques are used or only part of the WordPress environment is loaded in order to retrieve the values from the database. It’s best to use a static .css file instead.
2. In the PHP file, the code (CSS rules mixed with PHP variables and conditional clauses) will be harder to read by developers when they need to check out something. Sure, the file can be run in the browser (although I’m sure when it’s printed, it won’t even be indented or nice looking) but if you have a local copy of the project and browse through the theme’s code and you need to find a CSS or JavaScript syntax (in case script.php would be used), then it would make readability harder.

The solution: Save any custom CSS outside the plugin directory. Example: /wp-content/uploads/theme-name-custom-css/style-5.css. This way, in case the theme or plugin get updated, then the custom file will not be lost.

10. Not Using the Right Architecture (Code Organization) for the WordPress Plugins and Themes

Depending on the size and nature of the plugin (e.g., a standalone plugin or a plugin extension that works only if a main plugin is activated such as WooCommerce), the right architecture and code organization has to be set up.

If you have to built a single-purpose WordPress plugin for a client and it has a limited interaction with WordPress core, themes, and other plugins, it’s not effective to engineer complex classes unless you’re positive the plugin is going to expand considerably later on.

If the plugin is going to be featured rich with lots of code, then using an Objected Oriented Programming (OOP) coding approach (having lots of classes) would make sense. For instance, if you have lots of shortcodes, you can have them all kept in a separate class file such as class.shortcodes.php or if there are CSS and JavaScript files that are meant to be loaded within the Dashboard and front-end view then one class such as class.scripts.php can be used and enqueue the front-end files within a method such as enqueue_public_scripts() while enqueuing the files meant to load in the admin area within the enqueue_admin_scripts() method.

Instead of mixing the HTML with the PHP code, it’s better to keep it separated by implementing the MVC pattern into the plugins and themes. A good example is WooCommerce plugin. It has templates for various layouts that can also be overwritten easily through the theme or various filters just because the logic is separated from the design. The template containing the HTML layout is mostly used for printing the already processed information. Having HTML code within PHP methods is usually a bad practice (there are exceptions of course for small bits of HTML code), especially for a plugin that is maintained by more than one developer as it grows in size.

According to the WordPress Plugin Handbook, while there are a number of possible architecture patterns, they can be broadly grouped into three variations:

• Single plugin file, containing functions
• Single plugin file, containing a class, instantiated object, and, optionally, functions
• Main plugin file, then one or more class files

11. Not Taking WordPress Security Seriously When Writing Code

Security is often not taken seriously in WordPress development as many novice developers focus more on the results the client wants. All is fine until the client’s website gets hacked or your plugin published on WordPress.org has a vulnerability, leaving thousands of websites affected. These things happen sometimes and even the WordPress core has dealt with a fair number of security vulnerabilities since the early days of the CMS. It’s our responsibility to make it as secure as possible and, in case something does happen, to act promptly and make sure that we release a solid, well-tested patch.

Some of the most important security tips are:

XSS Vulnerabilities: To avoid this, two things have to be done: sanitize data input and sanitize output data. Depending on the data and the context it’s used in, there are several methods in WordPress to sanitize code. One should not trust any input data, nor any data that is going to be printed. One common function for sanitizing data input is sanitize_text_field(). It checks for invalid UTF-8 characters, converts single < characters to HTML entities, strip all tags, remove line breaks, tabs and extra white space and strip octets. As for printing data, a good example for outputting links is the esc_url() function, which rejects invalid URLs, eliminates invalid characters, and removes dangerous characters.

Prevent direct access to your files: Files can be directly accessed as most hosts allow that. However, if this happens and the code is not properly written to deal with it, some errors might be printed (e.g., missing functions or variables that are not declared) that would contain information valuable for potential attackers. One common code snippet that you often see in plugins and themes is:

// Exit if accessed directly
if ( ! defined( 'ABSPATH' ) ) exit;

If the constant ABSPATH is not defined (which should be for any WordPress install), then the script will exit and print nothing.

Use Nonces: As stated in the WordPress documentation, a nonce is a “number used once” to help protect URLs and forms from certain types of misuse, malicious or otherwise.

For instance, the following URL within the dashboard would be used to trash a post: http://example.com/wp-admin/post.php?post=123&action=trash—When accessing this URL, WordPress will validate authentication cookie information and if you have the right permission (e.g., you’re an administrator with all privileges), that post will get deleted.

What an attacker could do is make your browser access that URL without your knowledge by crafting a link on a third-party page like in the following example: <img src="http://example.com/wp-admin/post.php?post=123&action=trash" /> When making this request to WordPress, the browser will automatically attach your authentication cookie and WordPress would consider the request as valid.

That’s when a nonce comes into place as the attacker will not be able to get the nonce value (generated for the administrator that is actually logged into WordPress) that easily. The new request URL would look like this: http://example.com/wp-admin/post.php?post=123&action=trash&_wpnonce=b192fc4204

Without a valid nonce, a 403 Forbidden response would be sent to the browser by WordPress with the well-known error message: “Are you sure you want to do this?”

Although most people don’t take WordPress security seriously, thinking that their website would never get hacked, trusting the hosting (which can be helpful, but only to a certain point) and the fact that they purchased commercial plugins/themes (which often lead to the assumption that they are very secure), we should always make penetration tests for our websites in order to identify exploitable vulnerabilities before any hacker would be able to identify and exploit them.

Note that a large number of hacks out there are not even done by one person with the intention to specifically hack your website. Often, there are bots that scan WordPress websites automatically on a consistent basis and the moment a known vulnerability is found, it is exploited and the server used for spamming, getting private information from the database, placing hidden links within certain pages of the website that would lead to all sort of dodgy website (e.g., pornography, illicit drugs). Sometimes, the hacks are hidden so well that you need a proper scan of your website and see the date when specific files were updated in order to detect the hacked code. That’s why it’s good to even re-install WordPress (yes, the same version if you have the last one) so any hacked files would be overwritten by the genuine WordPress core files.

12. Using WordPress Functions and Code Snippets without Understanding Them

Often, when developers get stuck and find a solution on places like StackOverflow, they are just happy with the fact they managed to make something work without bothering to understand the logic behind that code or if that code can be altered to load faster or have less lines of code.

I’ve seen this practice so many times when snippets of code are copied within PHP scripts when only a third of that code is actually used.

This can have a few disadvantages, including:

1. The code does not use the same style as the existing project code. Yes, it’s comfortable to just copy and paste snippets that work out of the box and, although they are fine for a small personal project (it could turn into a big project someday, who knows), this practice is often not good when it comes to commercial work where a style consistency has to be kept.
2. Although the code does its job, it could contain ineffective functions that are not recommended for the task that needs to be achieved. If the code is not optimized, this “copy and paste” practice can lead to a slow and harder to maintain website, especially if more than one snippet is used on various locations within the project.
3. The code may not be licensed for reuse, and including the code in a client’s project can open them up to a lot of legal trouble.

Constant Improvement

Everyone makes mistakes, and each mistake is an opportunity to improve yourself. As WordPress developers, our industry moves at a very fast pace, and there’s never one set “right way” to do things. However, the more you practice and learn, the better you’ll become.

Do you disagree with any of the mistakes I pointed out, or think I missed one? Let me know in the comments and we’ll discuss.