As humans, mistakes are an inherent part of our existence. However, our ability to learn from these mistakes and avoid repeating them is what sets us apart. Many of my personal errors in the WordPress world stemmed from trying to save time during implementation, only to resurface later as issues. Making mistakes is a given, but proactively learning from our own blunders and those of others is essential.

Common Oversight #1: Disabling Debugging

You might wonder why you should use debugging if your code appears to be functioning correctly. Debugging, a built-in WordPress feature, displays all PHP errors, warnings, and notices, including those related to outdated functions. When turned off, crucial warnings and notices that could lead to future problems if not addressed promptly might be missed. Our goal is to ensure our code harmonizes with all other site elements. Therefore, always enable debugging during development when adding custom code to WordPress, but remember to deactivate it before launching the site.

Enabling this feature involves editing the wp-config.php file located in your WordPress installation’s root directory. A typical file snippet is shown below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// 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 all-inclusive list of configurable options, but this suggested setup should suffice for most debugging requirements.

Common Oversight #2: Utilizing the wp_head Hook to Add Scripts and Styles

You might wonder what’s wrong with adding scripts to your header template, especially since WordPress already includes numerous popular scripts. However, many developers add additional scripts using the wp_head hook, which can lead to multiple instances of the same script, potentially with different versions, being loaded.

This is where enqueuing comes in – the WordPress-recommended method for incorporating scripts and styles into your site. Enqueuing prevents plugin conflicts and manages any script dependencies by utilizing the built-in functions wp_enqueue_script and wp_enqueue_style for scripts and styles, respectively. The key difference between the two is that wp_enqueue_script offers an extra parameter to relocate the script to the page footer.

1
2
3
4
5

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 a script isn’t crucial for rendering above-the-fold content, moving it to the footer ensures faster loading of the initial view. Registering the script before enqueuing it is recommended as it enables other plugins to deregister it using the handle without altering your plugin’s core code. Moreover, if a registered script’s handle is listed as a dependency for another enqueued script, it will automatically load before the dependent script.

Common Oversight #3: Neglecting Child Themes and Altering WordPress Core Files

When planning to modify a theme, always create a child theme. Some developers make changes directly to the parent theme files, only to find their modifications overwritten and permanently lost after a theme update.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

/*
 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
*/

This example demonstrates the creation of a child theme based on the default WordPress theme, Twenty Sixteen. The most crucial line is the one containing “Template,” which must match the directory name of the parent theme you’re cloning from.

The same principle extends to WordPress core files – avoid the temptation of modifying them directly. Instead, utilize WordPress’s pluggable functions and filters to prevent your changes from being overwritten during a WordPress update. Pluggable functions allow overriding certain core functions, but this method is gradually being replaced by filters, which achieve the same outcome. Filters are inserted at the end of WordPress functions to enable modifications to their output. When using pluggable functions, it’s advisable to wrap your functions within if ( !function_exists() ) to avoid fatal errors that can occur when multiple plugins attempt to override the same pluggable function without this wrapper.

Common Oversight #4: Hardcoding Values

While hardcoding a value like a URL directly into the code might seem quicker initially, the time spent later on debugging and resolving resulting issues far outweighs the initial time saved. By employing the appropriate function to dynamically generate the desired output, we significantly simplify future maintenance and debugging efforts. For instance, if you migrate your site from a testing environment to a live one with hardcoded URLs, you’ll likely encounter a broken site. This is why using functions like the one below for generating file paths and links is crucial:

1
2
3
4
5
6

// 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 example of poor hardcoding practice is within custom queries. For instance, as a security measure, let’s say we change the default WordPress database table prefix from wp_ to a more unique one like wp743_. Our queries will break if we ever migrate the WordPress installation because table prefixes can differ across environments. To avoid this, we can utilize the table properties of the wpdb class:

1
2

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

Notice how instead of using the literal value wp_users for the table name, we let WordPress determine it. By employing these properties for generating table names, we ensure the retrieval of accurate results.

Common Oversight #5: Failing to Prevent Site Indexing

You might wonder why you’d want to prevent search engines from indexing your site, assuming that indexing is always beneficial. When constructing a website, it’s generally undesirable for search engines to index it before it’s fully developed and a permalink structure is established. Moreover, if you have a staging server for testing site updates, you don’t want search engines like Google indexing these duplicate pages. Multiple instances of identical content make it challenging for search engines to determine the most relevant version for a given search query. Consequently, search engines penalize sites with duplicate content, negatively impacting your search rankings.

As illustrated below, WordPress Reading Settings includes a checkbox labeled “Discourage search engines from indexing this site,” accompanied by a crucial note stating that “It is up to search engines to honor this request.”

Keep in mind that search engines often disregard this request. For reliable prevention of search engine indexing, modify your .htaccess file and include the following line:

1

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

Common Oversight #6: Not Verifying Plugin Activation

You might question the necessity of checking for a plugin function’s existence if your plugin is always active. While your plugin will likely be active 99% of the time, what about the remaining 1% when it’s deactivated for some reason? In such cases, your website might display unsightly PHP errors. To prevent this, we can verify if the plugin is active before calling its functions. When a plugin function is called from the front-end, we need to include the plugin.php library to use the is_plugin_active() function:

1
2
3
4

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

While generally reliable, this technique can falter if the author changes the main plugin directory name. A more robust approach involves checking for the existence of a class within the plugin:

1
2
3

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

Since authors are less likely to modify a plugin’s class name, this method is generally preferred.

Common Oversight #7: Overloading Resources

You might wonder why we should be selective in loading plugin resources for pages. There’s no justification for loading styles and scripts for a plugin that’s not utilized on the current page. By loading plugin files only when necessary, we reduce page loading time, enhancing the user experience. For instance, consider a WooCommerce site where we want the plugin loaded only on shopping pages. In such a scenario, we can selectively prevent unnecessary files from loading on other pages to minimize bloat. The following code can be added to the theme or plugin’s functions.php file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

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 using the wp_dequeue_script($handle) function via their registered handle. Similarly, wp_dequeue_style($handle) prevents stylesheets from loading. However, if implementation proves too challenging, you can install the Plugin Organizer plugin, which allows selectively loading plugins based on criteria like post type or page name. Remember to disable any active caching plugins like W3Cache to avoid constant cache refreshing to reflect your changes.

Common Oversight #8: Retaining the Admin Bar

While you might consider leaving the WordPress Admin Bar visible to everyone, bear in mind that admin pages often lack visual integration with your chosen theme, resulting in a disjointed experience. For a professional-looking site, disable the Admin Bar and provide a custom front-end account management page:

1
2
3
4
5
6
7

add_action('after_setup_theme', 'remove_admin_bar');

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

Adding this code to your theme’s functions.php file will display the Admin Bar only to site administrators. You can customize visibility further by adding any WordPress user roles or capabilities to the current_user_can($capability) function.

Common Oversight #9: Underutilizing the GetText Filter

While you might opt to use CSS or JavaScript to change a button’s label, this adds unnecessary code and increases rendering time. A more efficient approach is to utilize one of WordPress’s most versatile filters, gettext. Combined with a plugin’s textdomain – a unique identifier ensuring WordPress can distinguish between loaded translations – the gettext filter enables text modification before page rendering. Searching the source code for the function load_plugin_textdomain($domain) reveals the domain name required to override the target text. Reputable plugins ensure the textdomain is set upon plugin initialization. To modify theme text, look for the load_theme_textdomain($domain) line of code. Using WooCommerce as an example, we can modify the “Related Products” heading text by inserting the following code into your theme’s functions.php file:

1
2
3
4
5
6
7
8

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(), provided the textdomain is set using the mentioned functions.

1

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

Explore your plugins for these internationalization functions to discover other customizable strings.

Common Oversight #10: Sticking with Default Permalinks

By default, WordPress uses a query string containing the post ID to fetch content. However, this format is not user-friendly and users might accidentally remove crucial parts when copying the URL. More importantly, default permalinks lack a search engine-friendly structure. Enabling “pretty” permalinks ensures your URLs incorporate relevant keywords from the post title, improving search engine ranking performance. Retroactively changing permalinks, especially on a well-established site with numerous indexed posts, can be daunting. Therefore, immediately after installing WordPress, switch your permalink structure to a more search engine-friendly option beyond just the post ID. While I generally prefer using the post name, you can customize the permalink format to your liking using the available permalink structure tags.

In Conclusion

This article doesn’t encompass every mistake WordPress developers make. The key takeaway is to avoid taking shortcuts, a principle applicable to any development platform, not just WordPress. Time saved now through poor programming practices will inevitably lead to future headaches. Feel free to share your past mistakes and, more importantly, the lessons learned, in the comments below.