We are only human, and one of the traits of being a human is that we make mistakes. On the other hand, we are also self-correcting, meaning we tend to learn from our mistakes and hopefully are thereby able to avoid making the same ones twice. A lot of the mistakes I have made in the WordPress realm originate from trying to save time when implementing solutions. However, these would typically rear their heads down the road when issues would crop up as a result of this approach. Making mistakes is inevitable. However, learning from other people’s oversights (and your own of course!) is a road you should proactively take.

WordPress

Engineers look like superheroes, but we’re still human. Learn from us.

Common Mistake #1: Keeping the Debugging Off

Why should I use debugging when my code is working fine? Debugging is a feature built into WordPress that will cause all PHP errors, warnings, and notices (about deprecated functions, etc.) to be displayed. When debugging is turned off, there may be important warnings or notices being generated that we never see, but which might cause issues later if we don’t deal with them in time. We want our code to play nicely with all the other elements of our site. So, when adding any new custom code to WordPress, you should always do your development work with debugging turned on (but make sure to turn it off before deploying the site to production!).

To enable this feature, you’ll need to edit the wp-config.php file in the root directory of your WordPress install. Here is a snippet of a typical file:

// Enable debugging
define('WP_DEBUG', true);

// Log all errors to a text file located at /wp-content/debug.log
define('WP_DEBUG_LOG', true);

// Don’t display error messages write them to the log file /wp-content/debug.log
define('WP_DEBUG_DISPLAY', false);

// Ensure all PHP errors are written to the log file and not displayed on screen
@ini_set('display_errors', 0);

This is not an exhaustive list of configuration options that can be used, but this suggested setup should be sufficient for most debugging needs.

Common Mistake #2: Adding Scripts and Styles Using wp_head Hook

What is wrong with adding the scripts into my header template? WordPress already includes a plethora of popular scripts. Still, many developers will add additional scripts using the wp_head hook. This can result in the same script, but a different version, being loaded multiple times.

Enqueuing here comes to the rescue, which is the WordPress friendly way of adding scripts and styles to our website. We use enqueuing to prevent plugin conflicts and handle any dependencies a script might have. This is achieved by using the inbuilt functions wp_enqueue_script or wp_enqueue_style to enqueue scripts and styles respectively. The main difference between the two functions is that with wp_enqueue_script we have an additional parameter that allows us to move the script into the footer of the page.

wp_register_script( $handle, $src, $deps = array(), $ver = false, $in_footer = false )
wp_enqueue_script( $handle, $src = false, $deps = array(), $ver = false, $in_footer = false )

wp_register_style( $handle, $src, $deps = array(), $ver = false, $media = 'all' )
wp_enqueue_style( $handle, $src = false, $deps = array(), $ver = false, $media = 'all' )

If the script is not required to render content above the fold, we can safely move it to the footer to make sure the content above the fold loads quickly. It’s good practice to register the script first before enqueuing it, as this allows others to deregister your script via the handle in their own plugins, without modifying the core code of your plugin. In addition to this, if the handle of a registered script is listed in the array of dependencies of another script that has been enqueued, that script will automatically be loaded prior to loading that highlighted enqueued script.

Common Mistake #3: Avoiding Child Themes and Modifying WordPress Core Files

Always create a child theme if you plan on modifying a theme. Some developers will make changes to the parent theme files only to discover after an upgrade to the theme that their changes have been overwritten and lost forever.

To create a child theme, place a style.css file in a subdirectory of the child theme’s folder, with the following content:

/*
 Theme Name:   Twenty Sixteen Child
 Theme URI:    http://example.com/twenty-fifteen-child/
 Description:  Twenty Fifteen Child Theme
 Author:       John Doe
 Author URI:   http://example.com
 Template:     twentysixteen
 Version:      1.0.0
 License:      GNU General Public License v2 or later
 License URI:  http://www.gnu.org/licenses/gpl-2.0.html
 Tags:         light, dark, two-columns, right-sidebar, responsive-layout, accessibility-ready
 Text Domain:  twenty-sixteen-child
*/

The above example creates a child theme based on the default WordPress theme, Twenty Sixteen. The most important line of this code is the one containing the word “Template” which must match the directory name of the parent theme you are cloning the child from.

The same principles apply to WordPress core files: Don’t take the easy route by modifying the core files. Put in that extra bit of effort by employing WordPress pluggable functions and filters to prevent your changes from being overwritten after a WordPress upgrade. Pluggable functions let you override some core functions, but this method is slowly being phased out and replaced with filters. Filters achieve the same end result and are inserted at the end of WordPress functions to allow their output to be modified. A trick is always to wrap your functions with if ( !function_exists() ) when using pluggable functions since multiple plugins trying to override the same pluggable function without this wrapper will produce a fatal error.

Common Mistake #4: Hardcoding Values

Often it looks quicker to just hardcode a value (such as a URL) somewhere in the code, but the time spent down the road debugging and rectifying issues that arise as a result of this is far greater. By using the corresponding function to generate the desired output dynamically, we greatly simplify subsequent maintenance and debugging of our code. For example, if you migrate your site from a test environment to production with hardcoded URLs, all of a sudden you’ll notice your site it is not working. This is why we should employ functions, like the one listed below, for generating file paths and links:

// Get child theme directory uri
stylesheet_directory_uri();
//  Get parent theme directory
get_template_directory_uri();
// Retrieves url for the current site
 site_url();

Another bad example of hardcoding is when writing custom queries. For example, as a security measure, we change the default WordPress datatable prefix from wp_ to something a little more unique, like wp743_. Our queries will fail if we ever move the WordPress install, as the table prefixes can change between environments. To prevent this from happening, we can reference the table properties of the wpdb class:

global $wpdb;
$user_count = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->users" );

Notice how I am not using the value wp_users for the table name, but instead, I’m letting WordPress work it out. Using these properties for generating the table names will help ensure that we return the correct results.

Common Mistake #5: Not Stopping Your Site From Being Indexed

Why wouldn’t I want search engines to index my site? Indexing is good, right? Well, when building a website, you don’t want search engines to index your site until you have finished building it and have established a permalink structure. Furthermore, if you have a staging server where you test site upgrades, you don’t want search engines like Google indexing these duplicate pages. When there are multiple pieces of indistinguishable content, it is difficult for search engines to decide which version is more relevant to a search query. Search engines will in such cases penalize sites with duplicate content, and your site will suffer in search rankings as a result of this.

As shown below, WordPress Reading Settings has a checkbox that reads “Discourage search engines from indexing this site”, although this does have an important-to-note underneath stating that “It is up to search engines to honor this request”.

WordPress Reading Settings

Bear in mind that search engines often do not honor this request. Therefore, if you want to reliably prevent search engines from indexing your site, edit your .htaccess file and insert the following line:

Header set X-Robots-Tag "noindex, nofollow"

Common Mistake #6: Not Checking if a Plugin is Active

Why should I check if a plugin function exists if my plugin is always switched on? For sure, 99% of the time your plugin will be active. However, what about that 1% of the time when for some reason it has been deactivated? If and when this occurs, your website will probably display some ugly PHP errors. To prevent this, we can check to see if the plugin is active before we call its functions. If the plugin function is being called via the front-end, we need to include the plugin.php library in order to call the function is_plugin_active():

include_once( ABSPATH . 'wp-admin/includes/plugin.php' );
if ( is_plugin_active( 'plugin-folder/plugin-main-file.php' ) ) {
// Run plugin code
}

This technique is usually quite reliable. However, there could be instances where the author has changed the main plugin directory name. A more robust method would be to check for the existence of a class in the plugin:

if( class_exists( ‘WooCommerce’ ) ) {
	// The plugin WooCommerce is turned on
}

Authors are less likely to change the name of a plugin’s class, so I would generally recommend using this method.

Common Mistake #7: Loading Too Many Resources

Why should we be selective in loading plugin resources for pages? There is no valid reason to load styles and scripts for a plugin if that plugin is not used on the page that the user has navigated to. By only loading plugin files when necessary, we can reduce our page loading time, which will result in an improved end user experience. Take, for example, a WooCommerce site, where we only want the plugin to be loaded on our shopping pages. In such a case, we can selectively remove any files from being loaded on all the other sites pages to reduce bloating. We can add the following code to the theme or plugin’s functions.php file:

function load_woo_scripts_styles(){
	
if( function_exists( 'is_woocommerce' ) ){
    // Only load styles/scripts on Woocommerce pages   
	if(! is_woocommerce() && ! is_cart() && ! is_checkout() ) { 		
		
		// Dequeue scripts.
		wp_dequeue_script('woocommerce'); 
		wp_dequeue_script('wc-add-to-cart'); 
		wp_dequeue_script('wc-cart-fragments');
		
		// Dequeue styles.	
		wp_dequeue_style('woocommerce-general'); 
		wp_dequeue_style('woocommerce-layout'); 
		wp_dequeue_style('woocommerce-smallscreen'); 
			
		}
	}	
}

add_action( 'wp_enqueue_scripts', 'load_woo_scripts_styles');

Scripts can be removed with the function wp_dequeue_script($handle) via the handle with which they were registered. Similarly, wp_dequeue_style($handle) will prevent stylesheets from being loaded. However, if this is too challenging for you to implement, you can install the Plugin Organizer that provides the ability to load plugins selectively based on certain criteria, such as a post type or page name. It’s a good idea to disable any caching plugins, like W3Cache, that you may have switched on to stop you from having to refresh the cache constantly to reflect any changes you have made.

Common Mistake #8: Keeping the Admin Bar

Can’t I just leave the WordPress Admin Bar visible for everyone? Well, yes, you could allow your users access to the admin pages. However, these pages very often do not visually integrate with your chosen theme and don’t provide a seamless integration. If you want your site to look professional, you should disable the Admin Bar and provide a front-end account management page of your own:

add_action('after_setup_theme', 'remove_admin_bar');

function remove_admin_bar() {
if (!current_user_can('administrator') && !is_admin()) {
  show_admin_bar(false);
}
}

The above code, when copied into your theme’s functions.php file will only display the Admin Bar for administrators of the site. You can add any of the WordPress user roles or capabilities into the current_user_can($capability) function to exclude users from seeing the admin bar.

Common Mistake #9: Not Utilizing the GetText Filter

I can use CSS or JavaScript to change the label of a button, what’s wrong with that? Well, yes, you can. However, you’re adding superfluous code and extra time to render the button, when you can instead use one of the handiest filters in WordPress, called gettext. In conjunction with a plugin’s textdomain, a unique identifier that ensures WordPress can distinguish between all loaded translations, we can employ the gettext filter to modify the text before the page is rendered. If you search the source code for the function load_plugin_textdomain($domain), it will give you the domain name we need to override the text in question. Any reputable plugin will ensure that the textdomain for a plugin is set on initialization of the plugin. If it’s some text in a theme that you want to change, search for the load_theme_textdomain($domain) line of code. Using WooCommerce once again as an example, we can change the text that appears for the “Related Products” heading. Insert the following code into your theme’s functions.php file:

function translate_string( $translated_text, $untranslated_text, $domain ) {
	if ( $translated_text == 'Related Products') {
			$translated_text = __( 'Other Great Products', 'woocommerce' );
	}
	return $translated_text;
}

add_filter( 'gettext', 'translate_string', 15, 3 );

This filter hook is applied to the translated text by the internationalization functions __() and _e(), as long as the textdomain is set via the aforementioned functions.

_e( 'Related Products', 'woocommerce' );

Search your plugins for these internationalization functions to see what other strings you can customize.

By default, WordPress uses a query string with the post’s ID to return the specified content. However, this is not user-friendly and users may remove pertinent parts of the URL when copying it. More importantly, these default permalinks do not use a search engine friendly structure. Enabling what we call “pretty” permalinks will ensure our URLs contain relevant keywords from the post title to improve performance in search engine rankings. It can be quite a daunting task having to retrospectively modify your permalinks, especially if your site has been running for a significant period of time, and you’ve got hundreds of posts already indexed by search engines. So after you’ve installed WordPress, ensure you promptly change your permalinks structure to something a little more search engine friendly than just a post ID. I generally use the post name for the majority of sites I build, but you can customize the permalink to whatever format you like using the available permalink structure tags.

WordPress Permalink Settings

Conclusion

This article is by no means an exhaustive list of mistakes made by WordPress developers. If there’s one thing you should take away from this article, though, it’s that you should never take shortcuts (and that’s true in any development platform, not just in WordPress!). Time saved now by poor programming practices will come back to haunt you later. Feel free to share with us some mistakes that you have made in the past – and more importantly any lessons learned – by leaving a comment below.

About the author

Andrew Schultz, Australia
member since March 23, 2016
Andrew is an Australian engineer with a passion for travel. He's a highly capable professional specializing in WordPress with the ability to offer extensive technical expertise coupled with outstanding communication skills. His strengths include an ability to rapidly become familiar with new business processes & systems. He has over 10 years of experience working as an apps developer across the full project life-cycle. [click to continue...]
Hiring? Meet the Top 10 Freelance WordPress Developers for Hire in December 2016

Comments

fuzzylollipop
"WordPress is easily the most powerful open source blogging and content management system available online today" is what is known as a "dis/qualifying" statement. It disqualifies everything that comes after it as just as invalid. It is a "stop if they really said what they just said, they really don't know the problem domain as well as they think they do and most everything else will be just as wrong".
thomasbandit
I don't understand what you said. What is your alternative solution? Used properly WordPress is a very powerful, easily customisable CMS that enables many non-tech savvy users to publish content and run their own websites. In my opinion, there is nothing else that competes with it in terms of its popularity and use.
SolQuent
You beat me to it.
Matt
I agree
Michiel van der Blonk
It depends on what you use wordpress for. I used WordPress for the end users, and a custom Laravel application for the database back end. That way I get the best of both worlds. Users can easily write new content using posts and pages, and they can use a shortcode to remotely get data using a REST API, all invisible for the end user. They do not need to learn working with a new platform, and I have the luxury of using templates, designs and plugins.
paolo scutti
very interested in your solution, Michiel. Is there something annoying with it? (i.e. i use quite always acf for adding fields to some post types, widgets,etc. and while i see no trouble in retrieving acf values via the wp-api, i wonder if it works in the opposite, POST, way. of course your setup is different, but still wondering if you're not duplicatin everything). also i couldn't grasp the shortcode part you describe. But really felt this need a lot of times (but in my case i was building front part interface via acf front-end posting; had to filter and sanitize everything and, still, one of my sites was hacked. Reverted soon to standard wp admin bar :)
paolo scutti
or perhaps i misunderstood your comment :)
Trade Southwest
@fuzzylollipop I agree 99.9%. Wordpress is for people that do not know how to build (remarkable) HTML Websites and will use WP for all the wrong reasons. WP is a blogging platform. Too many peeps use it to build giant backlink farms and ruin the organic search efforts of whitehat programmers. WP is also too much work to make a Website look and feel the way your customer wants it. This is the gist of the article written by Andrew is that programmers [can] do (all) the wrong things - mostly because WP is open source---nothing wrong with OSource---and anyone can alter parts or change shortcodes to their own preference. I hard code all the time but I only use WP for clients that will never touch anything but one particular widget or plugin asset, therefore my hardcode is set in stone---yes I am aware of security and use WP built in sanitizers. Andrew brings up a few things which everyone would do mostly becase there is so much to know if you want to get the most out of WP, hence: back to @lollipops statement. Bottom line is: use WP best practices but don't use WP for building a "real" Website. It will rank better with pure HTML, (OK PHP with HTML templates - no MVC, just fast loading, low file count, no dependencies other than CDNs) so using a big engine has no advantage unless your client just does not have any other alternative to add content their self. I use my own CMS* and peeps can login and botta-bing, the job gets done. All websites are HTML in the browser, why go backwards. Yes you can argue that statement (asp, rb, etc) and you can argue WP does not make good websites; peeps like to argue, online. But good code practice starts with knowing how to build with DOM tools way before you should be spending months understanding WP control elements. The best WP builder will submit at least 5 or 10 themes to WP before they try to customize the client's theme. This is how I 'learned' WP engine best practices (OK, yeah I know, I said I hard code....) *https://github.com/tradesouthwest/details (trimmed down version---don't judge. My deployments can upload and handle everything WP does.)
fuzzylollipop
Mistake #1 "Using Wordpress in the first place" Mistake #2 "see also #1" Mistake #3 "see also #1" Mistake #4 "see also #1" Mistake #5 "see also #1" Mistake #6 "see also #1" Mistake #7 "see also #1" Mistake #8 "see also #1" Mistake #9 "see also #1"
astroanu
There's no such thing as "WordPress Developers"
fuzzylollipop
let me spell it out. The claim that "WordPress is easily the most powerful open source blogging and content management system available online today" is so ludricis and false that it colors everything else that the person that is making that comment is going to say afterwards and unreliable at best and just flat out incorrect at worst.
Dušan
I think that the biggest mistake is calling someone "Wordpress developer" and using Wordpress in the first place.
Ali Basheer
I am developing sites on top of Wordpress during the past 2 years, and I develop some projects using Laravel. What I ended up with this rule: use Wordpress for small and medium sites, use Laravel for Larger projects, specially those that will have mobile app.
Franz Pouchet
It's so restrictive and boxy. Lol
dojovader
Bolt cms, Process wire, October cms.
dojovader
Damn you beat me to it gave up wordpress, it's terrible
Duke Vukadinovic
In my opinion, one of the most common mistakes that many novice web designers tend to stick is the overuse of the default theme, which gives them a pretty basic looking website.
Alan Chavez
Mistake #0 "Developing in WordPress Remotely" There is absolutely no need to turn on debugging on a production site, or on the server where the production site will eventually be. Develop locally, and turn on all your debugging there. That way you don't have to tell web crawler to not index your site, and not turning on debugging. Mistake #11: Not caching your website. WordPress does 10 - 15 trips to the database to render a list of posts. Cache that stuff if the content isn't updated that often. Mistake #12: Not using PHP 7 It's a proven fact that WordPress runs twice as fast in PHP 7. Update your server, and see an increase in performance right away. Mistake #13: Not using WP-CLI Any developer who works with WordPress and isn't familiar with WP-CLI is making a disservice to himself. It's an amazing tool, learn it and use it.
Alan Chavez
Developing your own CMS sometimes is slightly worse than just using WordPress. Also, you create an open source project and ask people to not judge? The whole point of having an open source project is for people to judge and make contributions to it. That said, constructive feedback about your project in particular. Didn't really go through the whole thing but these are the things that stood out like a sore thumb: 1. Adhere to the standards. Use PSR-2. (Using PSR-2 will be a huge step towards using modern PHP) 2. Use autoloading. There's no need to use `require_once` in every page anymore 3. Lose the opinions. "col-md-6" what if I don't want to use Bootstrap? those template files are mixed together with your logic, or what if I don't want to use jQuery? You are claiming that WP does not make good websites, and I agree for a whole different set of reasons (like using 20 SQL statements to render a list of posts, or how massive the wp-query.php file is, that is so hard to debug when something goes wrong)
Trade Southwest
Alan, Thanks for your insights. what I meant by "don't judge" was to not compare the 'features' of the nano blog to what WP has, like uploads and media library plus plugins etc; yet your comment concerning OpenSource IS "gaugeable" is inline with what this article is about: mistakes that programmers make (with a blog)... so your suggestions are worth responding to. 1. PSR-2 is noted and will be implemented from here on out. (good call) 2. Will also note and use autoload. 3. I always put notes into OpenSource and even my private projects ( like fencedirectoryaz.com ). I tend to build so often that even I, have trouble remembering the page layout. Anyone can change any page elements in the DOM whenever they choose---and they usually do. So comments are always welcome in my boat. If you want to change "stuff" then at least I have saved you time so you can see what starts and what ends where. (Might be a whole topic for another Topal article.)
Steve
I agree 1 million times! I think WordPress is broken and outdated.
Bianca Sherawat
You absolutely find out the correct mistakes in wordpress thanku its really helpful for me to improve my wordpress skill.
comments powered by Disqus
Subscribe
The #1 Blog for Engineers
Get the latest content first.
No spam. Just great engineering and design posts.
The #1 Blog for Engineers
Get the latest content first.
Thank you for subscribing!
You can edit your subscription preferences here.
Trending articles
Relevant technologies
About the author
Andrew Schultz
JavaScript Developer
Andrew is an Australian engineer with a passion for travel. He's a highly capable professional specializing in WordPress with the ability to offer extensive technical expertise coupled with outstanding communication skills. His strengths include an ability to rapidly become familiar with new business processes & systems. He has over 10 years of experience working as an apps developer across the full project life-cycle.